@njeybe/nativ 2.4.1 → 2.5.1

package/dist/server/routes/telemetry-routes.js

@@ -0,0 +1,179 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { cacheHitRate, emptyActualUsage, loadTelemetry, mergeActualUsage, resolveModelPricing, } from '../../core/telemetry.js';
+import { runBench } from '../../commands/bench.js';
+import { HttpError } from '../http-utils.js';
+import { AI_DIR, planMilestones, readPlan } from '../plan-utils.js';
+import { runCaptured, truncateOutput } from '../cli-runner.js';
+export function finiteOr(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+export function percent(part, total) {
+    return total > 0 ? Math.round((part / total) * 100) : 0;
+}
+export function roundUsd(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+/** Telemetry is hand-editable JSON: coerce every counter so one bad record cannot NaN the totals. */
+export function sanitizeUsage(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const u = value;
+    const n = (v) => Math.max(0, finiteOr(v, 0));
+    return {
+        model: typeof u.model === 'string' ? u.model : 'unknown',
+        turns: n(u.turns),
+        inputTokens: n(u.inputTokens),
+        outputTokens: n(u.outputTokens),
+        cacheCreationTokens: n(u.cacheCreationTokens),
+        cacheReadTokens: n(u.cacheReadTokens),
+        thinkingTokens: n(u.thinkingTokens),
+        costUsd: n(u.costUsd),
+    };
+}
+export function aggregateActualUsage(records) {
+    let total = emptyActualUsage('');
+    for (const record of records) {
+        const usage = sanitizeUsage(record?.actualUsage);
+        if (usage)
+            total = mergeActualUsage(total, usage);
+    }
+    return total;
+}
+/** Usage as served by the API: the stored counters plus the derived cache hit rate. */
+export function usageView(usage) {
+    return usage ? { ...usage, costUsd: roundUsd(usage.costUsd), cacheHitRate: cacheHitRate(usage) } : null;
+}
+/** GET /api/pipeline/benchmarks: the cached report written by `nativ bench` or benchmarks/run. */
+export function handleBenchmarks(root) {
+    let report = null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(root, AI_DIR, 'benchmark_report.json'), 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            report = parsed;
+    }
+    catch {
+        // No benchmark has been run yet, or the report is unreadable.
+    }
+    return { ok: true, report };
+}
+export function createBenchmarkRunner(root) {
+    let benchmarkRun = null;
+    return () => {
+        benchmarkRun ??= runCaptured(() => runBench(root, { json: true }))
+            .then(({ result, output }) => {
+            if (!result)
+                throw new HttpError(500, 'BENCHMARK_FAILED', truncateOutput(output || 'Benchmark suite failed to run'));
+            return result;
+        })
+            .finally(() => {
+            benchmarkRun = null;
+        });
+        return benchmarkRun;
+    };
+}
+/**
+ * GET /api/pipeline/telemetry/detailed: per-task financial audit. Each breakdown pairs the heuristic
+ * estimate with API-reported usage and lists the task's runs (engine, model, per-run usage).
+ */
+export function handleTelemetryDetailed(root, supervisor) {
+    const telemetry = loadTelemetry(path.join(root, AI_DIR, 'telemetry.json'));
+    const records = telemetry.tasks.filter((t) => Boolean(t) && typeof t.taskId === 'string');
+    const planTasks = new Map(planMilestones(readPlan(root)).flatMap((m) => m.tasks).map((t) => [t.id, t]));
+    const runsByTask = new Map();
+    for (const run of supervisor.listRuns()) {
+        const list = runsByTask.get(run.taskId) ?? [];
+        list.push(run);
+        runsByTask.set(run.taskId, list);
+    }
+    const taskIds = [...new Set([...records.map((r) => r.taskId), ...runsByTask.keys()])];
+    const taskBreakdowns = taskIds
+        .map((taskId) => {
+        const record = records.find((r) => r.taskId === taskId);
+        const planTask = planTasks.get(taskId);
+        const actual = sanitizeUsage(record?.actualUsage);
+        const estimate = record?.tokens;
+        const estimated = estimate
+            ? {
+                inputTokens: finiteOr(estimate.inputEstimated, 0),
+                outputTokens: finiteOr(estimate.outputEstimated, 0),
+                totalTokens: finiteOr(estimate.totalEstimated, 0),
+                costUsd: finiteOr(estimate.costUsdEstimated, 0),
+            }
+            : null;
+        return {
+            taskId,
+            title: record?.title ?? planTask?.title ?? taskId,
+            assignedSubagent: record?.assignedSubagent ?? planTask?.assignedSubagent ?? null,
+            status: planTask?.status ?? record?.status ?? null,
+            startedAt: record?.startedAt ?? null,
+            completedAt: record?.completedAt ?? null,
+            durationMs: finiteOr(record?.durationMs, 0),
+            verification: record?.verification ?? null,
+            estimated,
+            actual: usageView(actual),
+            // Positive: the task cost more than estimated.
+            varianceUsd: actual && estimated ? roundUsd(actual.costUsd - estimated.costUsd) : null,
+            runs: (runsByTask.get(taskId) ?? []).map((run) => ({
+                runId: run.runId,
+                engine: run.engine,
+                model: run.model,
+                status: run.status,
+                startedAt: run.startedAt,
+                endedAt: run.endedAt,
+                durationMs: run.durationMs,
+                thinking: run.thinking,
+                usage: usageView(sanitizeUsage(run.usage)),
+            })),
+        };
+    })
+        // Most expensive first; tasks without grounded usage keep their telemetry order at the end.
+        .sort((a, b) => (b.actual?.costUsd ?? -1) - (a.actual?.costUsd ?? -1));
+    const byModel = new Map();
+    for (const record of records) {
+        const usage = sanitizeUsage(record.actualUsage);
+        if (!usage)
+            continue;
+        byModel.set(usage.model, mergeActualUsage(byModel.get(usage.model) ?? emptyActualUsage(usage.model), usage));
+    }
+    const { summary } = telemetry;
+    const actual = aggregateActualUsage(records);
+    return {
+        ok: true,
+        summary: {
+            projectName: telemetry.projectName,
+            lastUpdated: telemetry.lastUpdated,
+            modelTierDefault: telemetry.modelTierDefault,
+            tasksTracked: records.length,
+            totalTasksCompleted: finiteOr(summary?.totalTasksCompleted, 0),
+            totalDurationMs: finiteOr(summary?.totalDurationMs, 0),
+            estimated: {
+                totalTokens: finiteOr(summary?.estimatedTotalTokens, 0),
+                costUsd: finiteOr(summary?.estimatedTotalCostUsd, 0),
+            },
+            actual: {
+                turns: actual.turns,
+                inputTokens: actual.inputTokens,
+                outputTokens: actual.outputTokens,
+                cacheReadTokens: actual.cacheReadTokens,
+                cacheCreationTokens: actual.cacheCreationTokens,
+                thinkingTokens: actual.thinkingTokens,
+                spendUsd: roundUsd(actual.costUsd),
+                cacheHitRate: cacheHitRate(actual),
+                // What the cache reads would have cost at each model's full input rate, minus what they did cost.
+                cacheSavingsUsd: roundUsd([...byModel.values()].reduce((sum, u) => {
+                    const rates = resolveModelPricing(u.model);
+                    return sum + (u.cacheReadTokens * (rates.inputPerM - rates.cacheReadPerM)) / 1_000_000;
+                }, 0)),
+            },
+            byModel: [...byModel.values()].map(usageView).sort((a, b) => b.costUsd - a.costUsd),
+            verification: {
+                passRate: finiteOr(summary?.verificationPassRate, 1),
+                runs: finiteOr(summary?.totalVerificationsRun, 0),
+                passed: finiteOr(summary?.totalVerificationsPassed, 0),
+            },
+            circuitBreakerTrips: finiteOr(summary?.circuitBreakerTrips, 0),
+        },
+        taskBreakdowns,
+    };
+}

package/dist/server/routes/triage-routes.d.ts

@@ -0,0 +1,81 @@
+import { type SelfHealingEscalationRecord } from '../../governor/index.js';
+import { Tier1Liaison, type TriageEvaluation } from '../../core/tier1-liaison.js';
+import type { EscalationFile } from '../../scanner/types.js';
+export declare const ESCALATION_FILTERS: readonly ["all", "pending_review", "resolved"];
+export type EscalationFilter = (typeof ESCALATION_FILTERS)[number];
+/** Escalation records as the resolve endpoint leaves them. */
+export interface ResolvedEscalationRecord extends SelfHealingEscalationRecord {
+    resolvedAt?: string;
+    resolution?: {
+        decision: 'approve' | 'reject';
+        proposalApplied: boolean;
+        ruleId: string | null;
+        unblockedTaskId: string | null;
+    };
+}
+export declare function escalationFilePath(root: string): string;
+/** Null when no escalation has ever been filed. */
+export declare function readEscalationFile(root: string): EscalationFile | null;
+/** tmp-file + rename so the SSE watcher and concurrent readers never observe a half-written file. */
+export declare function writeJsonAtomic(file: string, data: unknown): void;
+/** Moves a blocked task back to pending so it can be dispatched again. False when it was not blocked. */
+export declare function unblockTask(root: string, taskId: string, note: string): Promise<boolean>;
+/** Test restorations run where the task's files live: its agent worktree if one exists, else the project. */
+export declare function taskWorkspace(root: string, taskId: string): string;
+/**
+ * GET /api/pipeline/escalations?status=pending_review|resolved|all: escalations newest first, each
+ * with its optional self-healing `proposedPatch`. `resolved` covers every closed record (approved or rejected).
+ */
+export declare function handleEscalations(root: string, searchParams: URLSearchParams): {
+    ok: boolean;
+    escalations: import("../../scanner/types.js").EscalationRecord[];
+};
+/**
+ * POST /api/pipeline/escalations/resolve: `approve` applies the self-healing proposal (re-checked
+ * against the live contract), resets the circuit breaker and unblocks the task; `reject` dismisses
+ * the escalation and leaves the task blocked. A proposal that no longer applies leaves the
+ * escalation pending and returns 400.
+ */
+export declare function handleEscalationResolve(root: string, body: Record<string, unknown>): Promise<{
+    ok: boolean;
+    message: string;
+    unblockedTaskId: string | null;
+}>;
+/** The contract's evaluate body; the full verdict (patch, proof, guardrails) is stored on the escalation. */
+export declare function triageView(result: TriageEvaluation): {
+    humanCard?: import("../../core/tier1-liaison.js").HumanDecisionCard | undefined;
+    ok: boolean;
+    escalationId: string;
+    provider: string;
+    model: string;
+    source: import("../../core/tier1-liaison.js").TriageSource;
+    latencyMs: number;
+    classification: import("../../core/tier1-liaison.js").TriageClassification;
+    reasoning: string;
+    autoPatchApplied: boolean;
+};
+/**
+ * POST /api/pipeline/triage/evaluate: runs the Tier 1 strategist on one escalation. A proven additive
+ * patch is written only while auto-triage is enabled, and then unblocks the task. Concurrent requests
+ * for the same escalation share one evaluation, so a double-click cannot apply or count twice.
+ */
+export declare function handleTriageEvaluate(root: string, liaison: Tier1Liaison, inFlight: Map<string, Promise<ReturnType<typeof triageView>>>, body: Record<string, unknown>): Promise<{
+    humanCard?: import("../../core/tier1-liaison.js").HumanDecisionCard | undefined;
+    ok: boolean;
+    escalationId: string;
+    provider: string;
+    model: string;
+    source: import("../../core/tier1-liaison.js").TriageSource;
+    latencyMs: number;
+    classification: import("../../core/tier1-liaison.js").TriageClassification;
+    reasoning: string;
+    autoPatchApplied: boolean;
+}>;
+export declare const RISK_THRESHOLDS: string[];
+/** POST /api/pipeline/triage/config: session-only auto-triage settings, validated before they reach the liaison. */
+export declare function handleTriageConfig(liaison: Tier1Liaison, body: Record<string, unknown>, onToggle?: () => void): {
+    ok: true;
+    config: import("../../core/tier1-liaison.js").TriageConfig;
+};
+/** Automatically triages pending escalations when autoTriage is enabled. */
+export declare function runAutoTriageQueue(root: string, liaison: Tier1Liaison, inFlight: Map<string, Promise<ReturnType<typeof triageView>>>): Promise<void>;

package/dist/server/routes/triage-routes.js

@@ -0,0 +1,244 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { withFileLock, withPlanLock } from '../../core/lock-manager.js';
+import { CircuitBreaker, applySelfHealingProposal, } from '../../governor/index.js';
+import { finalizeTriage, triageBlocker } from '../../commands/triage.js';
+import { HttpError } from '../http-utils.js';
+import { AI_DIR, TASK_ID_PATTERN, findTask } from '../plan-utils.js';
+export const ESCALATION_FILTERS = ['all', 'pending_review', 'resolved'];
+const MAX_REASON_LENGTH = 1000;
+export function escalationFilePath(root) {
+    return path.join(root, AI_DIR, 'escalation.json');
+}
+/** Null when no escalation has ever been filed. */
+export function readEscalationFile(root) {
+    let raw;
+    try {
+        raw = fs.readFileSync(escalationFilePath(root), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    // withFileLock creates the file empty when it takes the first lock.
+    if (!raw.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed?.escalations))
+            parsed.escalations = [];
+        return parsed;
+    }
+    catch {
+        throw new HttpError(500, 'ESCALATION_FILE_CORRUPT', '.ai/escalation.json is not valid JSON');
+    }
+}
+/** tmp-file + rename so the SSE watcher and concurrent readers never observe a half-written file. */
+export function writeJsonAtomic(file, data) {
+    const tmp = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.renameSync(tmp, file);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (attempt >= 10 || (code !== 'EPERM' && code !== 'EBUSY')) {
+                fs.rmSync(tmp, { force: true });
+                throw err;
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+        }
+    }
+}
+/** Moves a blocked task back to pending so it can be dispatched again. False when it was not blocked. */
+export async function unblockTask(root, taskId, note) {
+    const planPath = path.join(root, AI_DIR, 'master_plan.json');
+    if (!fs.existsSync(planPath))
+        return false;
+    const result = await withPlanLock(planPath, (plan, ctx) => {
+        const task = findTask(plan, taskId);
+        if (!task || task.status !== 'blocked') {
+            ctx.abort();
+            return false;
+        }
+        task.status = 'pending';
+        task.notes = note;
+        return true;
+    });
+    return result === true;
+}
+/** Test restorations run where the task's files live: its agent worktree if one exists, else the project. */
+export function taskWorkspace(root, taskId) {
+    const worktree = path.join(root, '.worktrees', `task-${taskId}`);
+    return fs.existsSync(path.join(worktree, '.git')) ? worktree : root;
+}
+/**
+ * GET /api/pipeline/escalations?status=pending_review|resolved|all: escalations newest first, each
+ * with its optional self-healing `proposedPatch`. `resolved` covers every closed record (approved or rejected).
+ */
+export function handleEscalations(root, searchParams) {
+    const rawFilter = searchParams.get('status') || 'all';
+    if (!ESCALATION_FILTERS.includes(rawFilter)) {
+        throw new HttpError(400, 'VALIDATION_ERROR', `"status" must be one of: ${ESCALATION_FILTERS.join(', ')}`);
+    }
+    const filter = rawFilter;
+    const escalations = (readEscalationFile(root)?.escalations ?? [])
+        .filter((e) => e && typeof e.id === 'string')
+        .filter((e) => filter === 'all' || (filter === 'pending_review' ? e.status === 'pending_review' : e.status !== 'pending_review'))
+        .sort((a, b) => (Date.parse(b.timestamp) || 0) - (Date.parse(a.timestamp) || 0));
+    return { ok: true, escalations };
+}
+/**
+ * POST /api/pipeline/escalations/resolve: `approve` applies the self-healing proposal (re-checked
+ * against the live contract), resets the circuit breaker and unblocks the task; `reject` dismisses
+ * the escalation and leaves the task blocked. A proposal that no longer applies leaves the
+ * escalation pending and returns 400.
+ */
+export async function handleEscalationResolve(root, body) {
+    const escalationId = typeof body.escalationId === 'string' ? body.escalationId.trim() : '';
+    if (!TASK_ID_PATTERN.test(escalationId)) {
+        throw new HttpError(400, 'VALIDATION_ERROR', '"escalationId" must be an escalation id such as esc-01');
+    }
+    const { decision } = body;
+    if (decision !== 'approve' && decision !== 'reject') {
+        throw new HttpError(400, 'VALIDATION_ERROR', `"decision" must be 'approve' or 'reject'`);
+    }
+    if (body.notes !== undefined && body.notes !== null && typeof body.notes !== 'string') {
+        throw new HttpError(400, 'VALIDATION_ERROR', '"notes" must be a string');
+    }
+    const notes = typeof body.notes === 'string' ? body.notes.trim() : '';
+    if (notes.length > MAX_REASON_LENGTH) {
+        throw new HttpError(400, 'VALIDATION_ERROR', `"notes" must be at most ${MAX_REASON_LENGTH} characters`);
+    }
+    const file = escalationFilePath(root);
+    if (!readEscalationFile(root))
+        throw new HttpError(400, 'ESCALATION_NOT_FOUND', `Escalation "${escalationId}" not found`);
+    // One resolution at a time per project: a double-click must not apply a proposal twice.
+    return withFileLock(file, async () => {
+        const data = readEscalationFile(root);
+        const record = data?.escalations.find((e) => e?.id === escalationId);
+        if (!data || !record)
+            throw new HttpError(400, 'ESCALATION_NOT_FOUND', `Escalation "${escalationId}" not found`);
+        if (record.status !== 'pending_review') {
+            throw new HttpError(400, 'ESCALATION_ALREADY_RESOLVED', `Escalation "${escalationId}" is already ${record.status}`);
+        }
+        const proposal = record.proposedPatch;
+        const now = new Date().toISOString();
+        let applied = null;
+        let unblockedTaskId = null;
+        let message;
+        if (decision === 'approve') {
+            if (proposal) {
+                const workspace = proposal.kind === 'restore_tests' ? taskWorkspace(root, record.taskId) : root;
+                applied = applySelfHealingProposal(workspace, record.taskId, proposal);
+                if (!applied.applied) {
+                    throw new HttpError(400, applied.ruleId, `Proposal ${proposal.proposalId} was not applied: ${applied.message}`);
+                }
+            }
+            else {
+                CircuitBreaker.recordSuccess(root, record.taskId);
+            }
+            const unblocked = await unblockTask(root, record.taskId, `Unblocked by escalation ${escalationId}${notes ? `: ${notes}` : ''}`);
+            unblockedTaskId = unblocked ? record.taskId : null;
+            record.status = 'resolved';
+            record.resolutionNotes = notes || applied?.message || 'Approved by operator';
+            message = [
+                applied ? `${applied.message}.` : `Escalation ${escalationId} approved.`,
+                unblocked ? `Task ${record.taskId} is unblocked and pending.` : `Task ${record.taskId} was not blocked.`,
+            ].join(' ');
+        }
+        else {
+            record.status = 'dismissed';
+            record.resolutionNotes = notes || (proposal ? `Proposal ${proposal.proposalId} rejected by operator` : 'Rejected by operator');
+            message = `Escalation ${escalationId} rejected; task ${record.taskId} stays blocked.`;
+        }
+        record.resolvedAt = now;
+        record.resolution = {
+            decision,
+            proposalApplied: Boolean(applied?.applied),
+            ruleId: applied?.ruleId ?? null,
+            unblockedTaskId,
+        };
+        data.lastUpdated = now;
+        writeJsonAtomic(file, data);
+        return { ok: true, message, unblockedTaskId };
+    });
+}
+/** The contract's evaluate body; the full verdict (patch, proof, guardrails) is stored on the escalation. */
+export function triageView(result) {
+    return {
+        ok: true,
+        escalationId: result.escalationId,
+        provider: result.provider,
+        model: result.model,
+        source: result.source,
+        latencyMs: result.latencyMs,
+        classification: result.classification,
+        reasoning: result.reasoning,
+        autoPatchApplied: result.autoPatchApplied,
+        ...(result.humanCard ? { humanCard: result.humanCard } : {}),
+    };
+}
+/**
+ * POST /api/pipeline/triage/evaluate: runs the Tier 1 strategist on one escalation. A proven additive
+ * patch is written only while auto-triage is enabled, and then unblocks the task. Concurrent requests
+ * for the same escalation share one evaluation, so a double-click cannot apply or count twice.
+ */
+export function handleTriageEvaluate(root, liaison, inFlight, body) {
+    const escalationId = typeof body.escalationId === 'string' ? body.escalationId.trim() : '';
+    if (!TASK_ID_PATTERN.test(escalationId)) {
+        throw new HttpError(400, 'VALIDATION_ERROR', '"escalationId" must be an escalation id such as esc-01');
+    }
+    const running = inFlight.get(escalationId);
+    if (running)
+        return running;
+    const evaluation = (async () => {
+        const blocker = triageBlocker(root, escalationId);
+        if (blocker)
+            throw new HttpError(400, 'TRIAGE_REJECTED', blocker);
+        const result = await liaison.evaluate(escalationId);
+        if (!result.ok)
+            throw new HttpError(400, 'TRIAGE_REJECTED', result.error);
+        await finalizeTriage(root, result);
+        return triageView(result);
+    })().finally(() => inFlight.delete(escalationId));
+    inFlight.set(escalationId, evaluation);
+    return evaluation;
+}
+export const RISK_THRESHOLDS = ['safe_contracts_only', 'all_non_destructive'];
+/** POST /api/pipeline/triage/config: session-only auto-triage settings, validated before they reach the liaison. */
+export function handleTriageConfig(liaison, body, onToggle) {
+    if (typeof body.autoTriageEnabled !== 'boolean') {
+        throw new HttpError(400, 'VALIDATION_ERROR', '"autoTriageEnabled" must be a boolean');
+    }
+    if (body.riskThreshold !== undefined && !RISK_THRESHOLDS.includes(body.riskThreshold)) {
+        throw new HttpError(400, 'VALIDATION_ERROR', `"riskThreshold" must be one of: ${RISK_THRESHOLDS.join(', ')}`);
+    }
+    const result = liaison.updateConfig({ autoTriageEnabled: body.autoTriageEnabled, riskThreshold: body.riskThreshold });
+    if (!result.ok)
+        throw new HttpError(400, 'VALIDATION_ERROR', result.error);
+    if (body.autoTriageEnabled && onToggle)
+        onToggle();
+    return result;
+}
+/** Automatically triages pending escalations when autoTriage is enabled. */
+export async function runAutoTriageQueue(root, liaison, inFlight) {
+    const status = liaison.getStatus();
+    if (!status.autoTriageEnabled)
+        return;
+    const data = readEscalationFile(root);
+    if (!data?.escalations)
+        return;
+    const pending = data.escalations.filter((e) => e && e.status === 'pending_review' && !e.triage);
+    for (const esc of pending) {
+        if (inFlight.has(esc.id))
+            continue;
+        try {
+            await handleTriageEvaluate(root, liaison, inFlight, { escalationId: esc.id });
+        }
+        catch {
+            // Background auto-triage gracefully ignores individual failures
+        }
+    }
+}

package/dist/server/routes/worktree-routes.d.ts

@@ -0,0 +1,31 @@
+import { type WorktreeInfo } from '../../commands/worktree.js';
+import type { MasterPlanTask } from '../../scanner/types.js';
+export interface PipelineWorktree extends WorktreeInfo {
+    taskStatus: MasterPlanTask['status'] | null;
+    mergeEligible: boolean;
+    mergeBlockedReason: string | null;
+}
+export declare function git(cwd: string, args: string[]): Promise<string>;
+/** `git diff --no-index` exits 1 when the inputs differ, so stdout is also read from that "error". */
+export declare function gitNoIndexDiff(cwd: string, file: string): Promise<string>;
+/** Async twin of `nativ worktree list --json` (which blocks on execSync and prints to the console). */
+export declare function listGitWorktrees(root: string): Promise<WorktreeInfo[]>;
+/**
+ * GET /api/pipeline/worktrees. Merge eligibility mirrors the `nativ worktree merge` gatekeeper (task completed,
+ * circuit breaker not tripped), and additionally requires the task to be declared in the plan.
+ */
+export declare function describeWorktrees(root: string): Promise<PipelineWorktree[]>;
+/** POST /api/pipeline/worktrees/action: `nativ worktree merge|remove`, never forced past the merge gatekeeper. */
+export declare function handleWorktreeAction(root: string, body: Record<string, unknown>): Promise<{
+    ok: boolean;
+    message: string;
+}>;
+/** GET /api/pipeline/worktrees/diff: uncommitted changes and unified diff for an agent worktree. */
+export declare function handleWorktreeDiff(root: string, searchParams: URLSearchParams): Promise<{
+    ok: boolean;
+    taskId: string;
+    branch: string;
+    hasChanges: boolean;
+    filesChanged: string[];
+    diff: string;
+}>;