rivet-design 0.8.6 → 0.9.1

package/dist/mcp/agent-variants/WorktreeOrchestrator.d.ts

@@ -0,0 +1,187 @@
+import type { ChildProcess } from 'child_process';
+import { AgentVariantsError } from './errors';
+import { SessionStore, type ApprovedBriefSelection, type ApproveResult, type ProposeArgs, type ProposeResult, type ReportCompleteResult, type RequestWorkResult } from './SessionStore';
+import type { Brief, Stage, TerminalSummary, WorkItemStatus } from './contracts';
+import type { PendingChangesAdapter } from './pendingChangesAdapter';
+/**
+ * Subset of WorktreeManager that the orchestrator depends on. Defined as an
+ * interface so unit tests can mock it without spinning up real git/processes.
+ *
+ * Each succeeded variant gets its own dev server so the user can cycle
+ * between live, running variants in the iframe via a proxy retarget.
+ */
+export interface WorktreeManagerLike {
+    createWorktrees(sessionId: string, count: number): Promise<string[]>;
+    getDiff(worktreePath: string): Promise<string>;
+    cleanupSession(sessionId: string): Promise<void>;
+    getFreePort(): Promise<number>;
+    startDevServer(worktreePath: string, port: number, cmd: string, args: string[], env: Record<string, string>): Promise<ChildProcess>;
+    stopDevServer(proc: ChildProcess, timeoutMs?: number): Promise<void>;
+    getProjectCwdInWorktree(worktreePath: string): Promise<string>;
+}
+/**
+ * Per-session resolved environment. Used to populate destinationPath on the
+ * variant envelope and (in fresh-project flows) the workspace target. Also
+ * feeds buildDevServerCommand so each variant's dev server gets the correct
+ * port flag for its framework.
+ */
+export interface ProjectEnvironment {
+    projectPath: string;
+    framework: string;
+    packageManager: string;
+    devCommand: string;
+    /** Builds (cmd, args, env) for spawning a dev server in a worktree on a
+     *  specific port. Defaults to a generic { packageManager, [devCommand,
+     *  '--port', port] } shape if not provided, but production wires this to
+     *  buildDevServerCommand from utils/devServerCommand.ts. */
+    buildDevCommand?: (port: number) => {
+        cmd: string;
+        args: string[];
+        env: Record<string, string>;
+    };
+}
+export interface OrchestratorDeps {
+    store: SessionStore;
+    worktreeManager: WorktreeManagerLike;
+    pendingChangesAdapter: PendingChangesAdapter;
+    resolveProjectEnvironment: (sessionId: string) => Promise<ProjectEnvironment>;
+    telemetry?: VariantsTelemetry;
+}
+/**
+ * Minimal telemetry surface the orchestrator depends on. Decoupled from
+ * TelemetryService so unit tests can pass a stub. Production wires this
+ * to the singleton TelemetryService instance.
+ */
+export interface VariantsTelemetry {
+    track(event: string, properties?: Record<string, unknown>): void;
+}
+/** Snapshot shape consumed by the iframe chip, both via SSE and the legacy
+ *  GET /api/variants/active endpoint. Single source of truth lives on the
+ *  orchestrator (`buildActiveSnapshot`) so both transports are consistent. */
+export type ActiveSnapshot = {
+    active: false;
+} | {
+    active: true;
+    sessionId: string;
+    stage: Stage;
+    briefs: Brief[];
+    progress: {
+        ready: number;
+        total: number;
+    };
+    summary: TerminalSummary | null;
+    variants: Array<{
+        workItemId: string;
+        status: import('./contracts').WorkItemStatus;
+        label?: string;
+        previewPort?: number;
+        worktreePath?: string;
+    }>;
+};
+/**
+ * Wraps SessionStore for the operations that have side effects: approve
+ * (provision worktrees), reportComplete (capture diff + auto-enqueue to
+ * pending changes), cancel (teardown). Pure read paths bypass and call
+ * SessionStore directly.
+ *
+ * This is the terminal-native variant of the orchestrator: the user picks
+ * a single brief upfront, so there's only ever one code-gen item per
+ * session and no live preview / proxy retarget. Once the agent reports
+ * the variant succeeded, the diff auto-enqueues to bridge — no separate
+ * pick step.
+ */
+export declare class AgentVariantsOrchestrator {
+    private readonly store;
+    private readonly worktrees;
+    private readonly adapter;
+    private readonly resolveEnv;
+    private readonly telemetry;
+    private readonly resources;
+    /** Most recent agent-variants sessionId — read by the iframe chip via
+     *  GET /api/variants/active. Cleared on cancel or commit. */
+    private activeSessionId;
+    /** Push channel for the iframe chip's SSE subscription. Emits an
+     *  ActiveSnapshot on every state change so the chip never has to poll. */
+    private readonly events;
+    constructor(deps: OrchestratorDeps);
+    propose(args: ProposeArgs): ProposeResult;
+    /** Returns the most recent agent-variants sessionId (or null). */
+    getActiveSessionId(): string | null;
+    /** Subscribe to active-snapshot pushes. Returns an unsubscribe fn. */
+    subscribeToEvents(listener: (snapshot: ActiveSnapshot) => void): () => void;
+    /** Build the snapshot the chip cares about. Reads from SessionStore +
+     *  per-resource state; safe to call at any time. */
+    buildActiveSnapshot(): ActiveSnapshot;
+    private emitChange;
+    reportBriefs(args: {
+        sessionId: string;
+        workItemId: string;
+        attempt: number;
+        leaseId?: string;
+        briefs: Brief[];
+    }): {
+        briefs: Brief[];
+    };
+    requestWork(args: {
+        sessionId: string;
+        leaseOwner: string;
+        requestedLeaseCount?: number;
+    }): RequestWorkResult;
+    getStage(sessionId: string): Stage;
+    getBriefs(sessionId: string): Brief[];
+    getProgress(sessionId: string): {
+        ready: number;
+        total: number;
+    };
+    getSummary(sessionId: string): TerminalSummary;
+    hasSession(sessionId: string): boolean;
+    /** Resolve a worktree path for a code-gen work item, if provisioned. */
+    getWorktreePath(sessionId: string, workItemId: string): string | undefined;
+    /** Resolve the dev server port for a code-gen work item, if running. */
+    getDevServerPort(sessionId: string, workItemId: string): number | undefined;
+    approve(args: {
+        sessionId: string;
+        selections: ApprovedBriefSelection[];
+    }): Promise<ApproveResult>;
+    reportComplete(args: {
+        sessionId: string;
+        workItemId: string;
+        leaseId: string;
+        attempt: number;
+        status: WorkItemStatus;
+        output?: unknown;
+        error?: {
+            code: string;
+            message: string;
+        };
+    }): Promise<ReportCompleteResult>;
+    cancel(args: {
+        sessionId: string;
+        reason?: string;
+    }): Promise<{
+        stage: 'cancelled';
+        cleanupStatus: 'pending' | 'complete' | 'partial';
+    }>;
+    /**
+     * User has reviewed the rendered variants in chat and picked one. Look up
+     * the captured diff, build a VariantPickEnvelope, and enqueue to the
+     * pending-changes channel. Idempotent on (sessionId, variantId): repeating
+     * the call returns duplicate=true without re-enqueueing.
+     */
+    commitVariant(args: {
+        sessionId: string;
+        variantId: string;
+    }): Promise<{
+        enqueued: boolean;
+        duplicate: boolean;
+        changedFilesCount: number;
+    }>;
+    /** Read the captured diff for a code-gen variant, if available. */
+    getVariantDiff(sessionId: string, variantId: string): string | undefined;
+    private provisionWorktrees;
+    private handleSucceededReport;
+    private teardownSession;
+    private ensureResources;
+}
+export type { AgentVariantsError };
+//# sourceMappingURL=WorktreeOrchestrator.d.ts.map

package/dist/mcp/agent-variants/WorktreeOrchestrator.d.ts.map

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

package/dist/mcp/agent-variants/WorktreeOrchestrator.js

@@ -0,0 +1,482 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentVariantsOrchestrator = void 0;
+const events_1 = require("events");
+const logger_1 = require("../../utils/logger");
+const errors_1 = require("./errors");
+const contracts_1 = require("./contracts");
+const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
+const NOOP_TELEMETRY = { track: () => undefined };
+/**
+ * Wraps SessionStore for the operations that have side effects: approve
+ * (provision worktrees), reportComplete (capture diff + auto-enqueue to
+ * pending changes), cancel (teardown). Pure read paths bypass and call
+ * SessionStore directly.
+ *
+ * This is the terminal-native variant of the orchestrator: the user picks
+ * a single brief upfront, so there's only ever one code-gen item per
+ * session and no live preview / proxy retarget. Once the agent reports
+ * the variant succeeded, the diff auto-enqueues to bridge — no separate
+ * pick step.
+ */
+class AgentVariantsOrchestrator {
+    store;
+    worktrees;
+    adapter;
+    resolveEnv;
+    telemetry;
+    resources = new Map();
+    /** Most recent agent-variants sessionId — read by the iframe chip via
+     *  GET /api/variants/active. Cleared on cancel or commit. */
+    activeSessionId = null;
+    /** Push channel for the iframe chip's SSE subscription. Emits an
+     *  ActiveSnapshot on every state change so the chip never has to poll. */
+    events = new events_1.EventEmitter();
+    constructor(deps) {
+        this.store = deps.store;
+        this.worktrees = deps.worktreeManager;
+        this.adapter = deps.pendingChangesAdapter;
+        this.resolveEnv = deps.resolveProjectEnvironment;
+        this.telemetry = deps.telemetry ?? NOOP_TELEMETRY;
+    }
+    // --- Pure delegations (no side effects) ---------------------------------
+    propose(args) {
+        const result = this.store.propose(args);
+        this.activeSessionId = result.sessionId;
+        this.ensureResources(result.sessionId);
+        this.telemetry.track('agent_variants.session_started', {
+            source: 'mcp',
+            sessionId: result.sessionId,
+            count: args.count ?? 4,
+            hasTarget: Boolean(args.target),
+            targetType: args.target?.type ?? null,
+            projectContextKind: args.projectContext?.kind ?? 'existing',
+        });
+        this.emitChange();
+        return result;
+    }
+    /** Returns the most recent agent-variants sessionId (or null). */
+    getActiveSessionId() {
+        return this.activeSessionId;
+    }
+    /** Subscribe to active-snapshot pushes. Returns an unsubscribe fn. */
+    subscribeToEvents(listener) {
+        this.events.on('change', listener);
+        return () => {
+            this.events.off('change', listener);
+        };
+    }
+    /** Build the snapshot the chip cares about. Reads from SessionStore +
+     *  per-resource state; safe to call at any time. */
+    buildActiveSnapshot() {
+        const sessionId = this.activeSessionId;
+        if (!sessionId || !this.store.hasSession(sessionId)) {
+            return { active: false };
+        }
+        const stage = this.store.getStage(sessionId);
+        const briefs = this.store.getBriefs(sessionId);
+        const progress = this.store.getProgress(sessionId);
+        const summary = stage === 'ready' ||
+            stage === 'degraded' ||
+            stage === 'failed' ||
+            stage === 'cancelled'
+            ? this.store.getSummary(sessionId)
+            : null;
+        const variants = (summary?.variants ?? []).map((v) => ({
+            workItemId: v.workItemId,
+            status: v.status,
+            label: v.label,
+            previewPort: this.getDevServerPort(sessionId, v.workItemId),
+            worktreePath: this.getWorktreePath(sessionId, v.workItemId),
+        }));
+        return {
+            active: true,
+            sessionId,
+            stage,
+            briefs,
+            progress,
+            summary,
+            variants,
+        };
+    }
+    emitChange() {
+        try {
+            this.events.emit('change', this.buildActiveSnapshot());
+        }
+        catch (err) {
+            log.warn('emitChange listener threw', err);
+        }
+    }
+    reportBriefs(args) {
+        const result = this.store.reportBriefs(args);
+        this.emitChange();
+        return result;
+    }
+    requestWork(args) {
+        const result = this.store.requestWork(args);
+        // Record lease times so variant_completed can report lease→report
+        // duration. (We don't fire a separate code_gen_leased event — the
+        // funnel signal we care about is per-variant completion duration.)
+        const resources = this.resources.get(args.sessionId);
+        if (resources) {
+            const now = Date.now();
+            for (const item of result.leasedWorkItems) {
+                resources.leasedAt.set(item.id, now);
+            }
+        }
+        // Decorate each leased item's input with the worktreePath provisioned
+        // by approve(). The skill instructs agents to write files to
+        // `input.worktreePath` — without this decoration that field would be
+        // missing and the agent would have no idea where to edit.
+        const decorated = {
+            ...result,
+            leasedWorkItems: result.leasedWorkItems.map((item) => {
+                const worktreePath = this.getWorktreePath(args.sessionId, item.id);
+                const baseInput = item.input && typeof item.input === 'object'
+                    ? item.input
+                    : {};
+                return {
+                    ...item,
+                    input: { ...baseInput, worktreePath },
+                };
+            }),
+        };
+        this.emitChange();
+        return decorated;
+    }
+    getStage(sessionId) {
+        return this.store.getStage(sessionId);
+    }
+    getBriefs(sessionId) {
+        return this.store.getBriefs(sessionId);
+    }
+    getProgress(sessionId) {
+        return this.store.getProgress(sessionId);
+    }
+    getSummary(sessionId) {
+        return this.store.getSummary(sessionId);
+    }
+    hasSession(sessionId) {
+        return this.store.hasSession(sessionId);
+    }
+    /** Resolve a worktree path for a code-gen work item, if provisioned. */
+    getWorktreePath(sessionId, workItemId) {
+        return this.resources.get(sessionId)?.worktrees.get(workItemId)
+            ?.worktreePath;
+    }
+    /** Resolve the dev server port for a code-gen work item, if running. */
+    getDevServerPort(sessionId, workItemId) {
+        return this.resources.get(sessionId)?.worktrees.get(workItemId)?.port;
+    }
+    // --- Mutation wrappers (state + side effects) ---------------------------
+    async approve(args) {
+        const result = this.store.approve(args);
+        this.ensureResources(args.sessionId);
+        this.telemetry.track('agent_variants.approved', {
+            source: 'mcp',
+            sessionId: args.sessionId,
+            approvedCount: result.approvedCount,
+            totalBriefs: result.totalCount,
+            isFresh: Boolean(result.scaffoldBaseWorkItemId),
+        });
+        this.emitChange();
+        // Await provisioning before returning so request_work always sees a
+        // populated worktreePath on each leased item. Provisioning is fast
+        // (`git worktree add` per variant + node_modules symlink), and the
+        // agent has nothing useful to do between approve and request_work
+        // anyway — running them serially is the contract the skill assumes.
+        try {
+            await this.provisionWorktrees(args.sessionId, result);
+            this.emitChange();
+        }
+        catch (err) {
+            log.error(`provisionWorktrees failed for session ${args.sessionId}`, err);
+            throw err;
+        }
+        return result;
+    }
+    async reportComplete(args) {
+        const result = this.store.reportComplete(args);
+        this.emitChange();
+        // Per-variant telemetry on terminal item statuses (skip 'running'
+        // heartbeats and the brief work item — only code_gen / scaffold_base
+        // matter for the funnel).
+        if (args.status === 'succeeded' ||
+            args.status === 'failed' ||
+            args.status === 'cancelled') {
+            const resources = this.resources.get(args.sessionId);
+            const leasedAt = resources?.leasedAt.get(args.workItemId);
+            const durationMs = leasedAt !== undefined ? Date.now() - leasedAt : null;
+            this.telemetry.track('agent_variants.variant_completed', {
+                source: 'mcp',
+                sessionId: args.sessionId,
+                workItemId: args.workItemId,
+                status: args.status,
+                attempt: args.attempt,
+                durationMs,
+                hasError: Boolean(args.error),
+                errorCode: args.error?.code ?? null,
+                isScaffold: resources?.scaffoldBaseWorkItemId === args.workItemId,
+            });
+        }
+        if (contracts_1.TERMINAL_STAGES.has(result.stage)) {
+            const resources = this.resources.get(args.sessionId);
+            if (resources && resources.terminalAt === undefined) {
+                resources.terminalAt = Date.now();
+                const totalLatencyMs = resources.terminalAt - resources.startedAt;
+                const summary = result.summary ?? this.store.getSummary(args.sessionId);
+                this.telemetry.track('agent_variants.terminal_state', {
+                    source: 'mcp',
+                    sessionId: args.sessionId,
+                    terminalStage: result.stage,
+                    successCount: summary.successCount,
+                    failureCount: summary.failureCount,
+                    cancelledCount: summary.cancelledCount,
+                    totalLatencyMs,
+                });
+            }
+        }
+        if (args.status === 'succeeded') {
+            void this.handleSucceededReport(args.sessionId, args.workItemId).catch((err) => {
+                log.error(`handleSucceededReport failed for ${args.sessionId}/${args.workItemId}`, err);
+            });
+        }
+        // Teardown is deferred to commitVariant / cancel. Terminal stage just
+        // means all variants are done; the user still needs to review and pick
+        // one. Resources (worktrees + captured diffs) live until that pick lands
+        // on the bridge.
+        return result;
+    }
+    async cancel(args) {
+        const stageBefore = this.store.hasSession(args.sessionId)
+            ? this.store.getStage(args.sessionId)
+            : null;
+        const result = this.store.cancel(args);
+        if (this.activeSessionId === args.sessionId) {
+            this.activeSessionId = null;
+        }
+        this.telemetry.track('agent_variants.cancelled', {
+            source: 'mcp',
+            sessionId: args.sessionId,
+            reason: args.reason ?? null,
+            fromStage: stageBefore,
+        });
+        this.emitChange();
+        void this.teardownSession(args.sessionId, 'cancel').catch((err) => {
+            log.error(`teardownSession failed for ${args.sessionId}`, err);
+        });
+        return result;
+    }
+    /**
+     * User has reviewed the rendered variants in chat and picked one. Look up
+     * the captured diff, build a VariantPickEnvelope, and enqueue to the
+     * pending-changes channel. Idempotent on (sessionId, variantId): repeating
+     * the call returns duplicate=true without re-enqueueing.
+     */
+    async commitVariant(args) {
+        // Idempotent path — SessionStore.recordVariantPick is the source of truth
+        // for which variant the user picked. If the same variant is being
+        // committed again, replay the previously stored envelope's metadata
+        // without going back through resources (which may have been torn down).
+        const existingPick = this.store.getVariantPick(args.sessionId);
+        if (existingPick && existingPick.variantId === args.variantId) {
+            return {
+                enqueued: false,
+                duplicate: true,
+                changedFilesCount: existingPick.changedFilesCount,
+            };
+        }
+        const resources = this.resources.get(args.sessionId);
+        if (!resources) {
+            throw new errors_1.AgentVariantsError('SESSION_NOT_FOUND', `No live resources for session ${args.sessionId} (already torn down?)`);
+        }
+        const record = resources.worktrees.get(args.variantId);
+        if (!record) {
+            throw new errors_1.AgentVariantsError('WORK_ITEM_NOT_FOUND', `Unknown variantId ${args.variantId} for session ${args.sessionId}`);
+        }
+        if (record.diff === undefined) {
+            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `Variant ${args.variantId} has no captured diff yet — wait for report_variant_complete(succeeded) first`);
+        }
+        const env = await this.resolveEnv(args.sessionId);
+        const input = this.store.getWorkItemInput(args.sessionId, args.variantId);
+        const projectContext = this.store.getProjectContext(args.sessionId);
+        const changedFilesCount = countDiffFiles(record.diff);
+        const payload = projectContext.kind === 'fresh'
+            ? {
+                kind: 'new-project',
+                destinationPath: projectContext.workspacePath,
+                sourceWorktreePath: record.worktreePath,
+                changedFilesCount,
+            }
+            : {
+                kind: 'diff',
+                diff: record.diff,
+                target: input.target,
+                changedFilesCount,
+            };
+        const envelope = {
+            sourceSessionId: args.sessionId,
+            variantId: args.variantId,
+            variantLabel: input.briefLabel,
+            destinationPath: projectContext.kind === 'fresh'
+                ? projectContext.workspacePath
+                : env.projectPath,
+            changedFilesCount,
+            payload,
+        };
+        // Record the pick in the SessionStore so future commitVariant calls with
+        // the same variantId are idempotent and a different variantId returns
+        // PENDING_CHANGE_CONFLICT (already picked).
+        this.store.recordVariantPick({
+            sessionId: args.sessionId,
+            envelope,
+        });
+        const enqueueResult = this.adapter.enqueue(envelope);
+        resources.committedVariantIds.add(args.variantId);
+        if (this.activeSessionId === args.sessionId) {
+            this.activeSessionId = null;
+        }
+        const dwellMsFromTerminal = resources.terminalAt
+            ? Date.now() - resources.terminalAt
+            : null;
+        this.telemetry.track('agent_variants.committed', {
+            source: 'mcp',
+            sessionId: args.sessionId,
+            workItemId: args.variantId,
+            payloadKind: payload.kind,
+            changedFilesCount,
+            dwellMsFromTerminal,
+            isFresh: projectContext.kind === 'fresh',
+        });
+        this.emitChange();
+        log.info(`Variant ${args.variantId} (${input.briefLabel}) committed by user → enqueued=${enqueueResult.enqueued}`);
+        // Once a variant is committed, the unpicked worktrees are no longer
+        // useful. Schedule teardown in the background so the agent's
+        // commit_variant call returns immediately.
+        void this.teardownSession(args.sessionId, 'committed').catch((err) => {
+            log.warn(`teardownSession after commit failed for ${args.sessionId}`, err);
+        });
+        return {
+            enqueued: enqueueResult.enqueued,
+            duplicate: enqueueResult.duplicate,
+            changedFilesCount,
+        };
+    }
+    /** Read the captured diff for a code-gen variant, if available. */
+    getVariantDiff(sessionId, variantId) {
+        return this.resources.get(sessionId)?.worktrees.get(variantId)?.diff;
+    }
+    // --- Side-effect implementations ----------------------------------------
+    async provisionWorktrees(sessionId, approveResult) {
+        const resources = this.ensureResources(sessionId);
+        const totalCount = approveResult.codeGenWorkItemIds.length +
+            (approveResult.scaffoldBaseWorkItemId ? 1 : 0);
+        if (totalCount === 0)
+            return;
+        log.info(`Provisioning ${totalCount} worktree(s) for session ${sessionId}`);
+        const paths = await this.worktrees.createWorktrees(sessionId, totalCount);
+        let cursor = 0;
+        if (approveResult.scaffoldBaseWorkItemId) {
+            resources.scaffoldBaseWorkItemId = approveResult.scaffoldBaseWorkItemId;
+            resources.worktrees.set(approveResult.scaffoldBaseWorkItemId, {
+                workItemId: approveResult.scaffoldBaseWorkItemId,
+                worktreePath: paths[cursor],
+            });
+            cursor += 1;
+        }
+        for (const id of approveResult.codeGenWorkItemIds) {
+            const path = paths[cursor];
+            cursor += 1;
+            resources.worktrees.set(id, { workItemId: id, worktreePath: path });
+        }
+    }
+    async handleSucceededReport(sessionId, workItemId) {
+        const resources = this.resources.get(sessionId);
+        const record = resources?.worktrees.get(workItemId);
+        if (!resources || !record) {
+            log.warn(`No worktree record for ${sessionId}/${workItemId}; skipping diff capture`);
+            return;
+        }
+        // scaffold_base sets up the base for dependent code_gen items. No diff
+        // to capture from it — its result is the disk state of the worktree.
+        if (resources.scaffoldBaseWorkItemId === workItemId) {
+            log.info(`scaffold_base ${workItemId} succeeded; awaiting dependent code-gen`);
+            return;
+        }
+        try {
+            record.diff = await this.worktrees.getDiff(record.worktreePath);
+            log.info(`Variant ${workItemId} diff captured (${countDiffFiles(record.diff)} files)`);
+            this.emitChange();
+        }
+        catch (err) {
+            log.warn(`getDiff failed for ${record.worktreePath}`, err);
+        }
+        // Bring up a dev server in the variant's worktree so the user can cycle
+        // through live variants in the iframe via the chip. Failures here are
+        // logged but non-fatal — the user can still pick by reading the diff.
+        try {
+            const env = await this.resolveEnv(sessionId);
+            const port = await this.worktrees.getFreePort();
+            const cwd = await this.worktrees.getProjectCwdInWorktree(record.worktreePath);
+            const { cmd, args, env: spawnEnv } = env.buildDevCommand
+                ? env.buildDevCommand(port)
+                : {
+                    cmd: env.packageManager,
+                    args: [env.devCommand, '--port', String(port)],
+                    env: { PORT: String(port) },
+                };
+            const proc = await this.worktrees.startDevServer(cwd, port, cmd, args, spawnEnv);
+            record.port = port;
+            record.devServerProcess = proc;
+            this.emitChange();
+            log.info(`Variant ${workItemId} dev server up on port ${port} (worktree ${record.worktreePath}; cmd: ${cmd} ${args.join(' ')})`);
+        }
+        catch (err) {
+            log.warn(`Failed to start dev server for variant ${workItemId}; live preview disabled for this variant`, err);
+        }
+    }
+    async teardownSession(sessionId, reason) {
+        const resources = this.resources.get(sessionId);
+        if (!resources)
+            return;
+        if (resources.cleanupStarted)
+            return;
+        resources.cleanupStarted = true;
+        log.info(`Tearing down session ${sessionId} (reason: ${reason})`);
+        // Stop dev servers in parallel; ignore individual failures.
+        const stops = [...resources.worktrees.values()]
+            .filter((r) => r.devServerProcess)
+            .map((r) => this.worktrees
+            .stopDevServer(r.devServerProcess)
+            .catch((err) => log.warn(`stopDevServer failed for ${sessionId}/${r.workItemId}`, err)));
+        await Promise.all(stops);
+        try {
+            await this.worktrees.cleanupSession(sessionId);
+        }
+        catch (err) {
+            log.warn(`cleanupSession (worktree removal) failed for ${sessionId}`, err);
+        }
+        this.resources.delete(sessionId);
+    }
+    ensureResources(sessionId) {
+        let r = this.resources.get(sessionId);
+        if (!r) {
+            r = {
+                sessionId,
+                worktrees: new Map(),
+                cleanupStarted: false,
+                committedVariantIds: new Set(),
+                startedAt: Date.now(),
+                leasedAt: new Map(),
+            };
+            this.resources.set(sessionId, r);
+        }
+        return r;
+    }
+}
+exports.AgentVariantsOrchestrator = AgentVariantsOrchestrator;
+function countDiffFiles(diff) {
+    // Each file in a unified diff starts with "diff --git ".
+    return (diff.match(/^diff --git /gm) ?? []).length;
+}
+//# sourceMappingURL=WorktreeOrchestrator.js.map