@njeybe/nativ 2.0.0

package/dist/core/setup-assets.js

@@ -0,0 +1,438 @@
+/**
+ * nativ · Single source for every file `nativ setup` generates.
+ *
+ * `planSetup` computes what each asset should contain and whether that differs from disk; `applySetup`
+ * writes the differences; `nativ doctor` reuses the same plan to detect drift. Everything merges into
+ * existing files: user-authored settings, servers and agent files are never overwritten.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { ROLE_ENV, loadEnforcementMode, parseJsonLoose } from './enforcement.js';
+import { resolveProjectRoot } from './root-resolver.js';
+import { isLegacyTemplate, normalizeForHash } from './legacy-templates.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const MCP_SERVER_NAME = 'nativ';
+export const AGENT_FILES = ['architect.md', 'worker.md', 'verifier.md'];
+const MANAGED_PREFIX = '<!-- nativ:managed sha256=';
+const MANAGED_PATTERN = /\n?<!-- nativ:managed sha256=([0-9a-f]{12}) -->\s*$/;
+const PRE_TOOL_USE_MATCHER = 'Write|Edit|MultiEdit|NotebookEdit';
+const SESSION_START_MATCHER = 'startup|resume|clear|compact';
+const HOOK_TIMEOUT_SECONDS = 10;
+// ─── CLI invocation ────────────────────────────────────────────────────────────────────────────────
+export function defaultHasBinary(name) {
+    try {
+        return spawnSync(process.platform === 'win32' ? 'where' : 'which', [name], { stdio: 'ignore' }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function quoteIfNeeded(part) {
+    return /[\s"]/.test(part) ? `"${part.replace(/"/g, '\\"')}"` : part;
+}
+export function resolveCliInvocation(options = {}) {
+    const explicit = options.command?.trim();
+    if (explicit) {
+        const [command, ...prefixArgs] = explicit.split(/\s+/);
+        return { command, prefixArgs, portable: ![command, ...prefixArgs].some((p) => path.isAbsolute(p)) };
+    }
+    if ((options.hasBinary ?? defaultHasBinary)('nativ'))
+        return { command: 'nativ', prefixArgs: [], portable: true };
+    // Not installed globally: fall back to this very build, which only works on this machine.
+    const self = path.resolve(__dirname, '..', '..', 'bin', 'cli.js').replace(/\\/g, '/');
+    return { command: 'node', prefixArgs: [self], portable: false };
+}
+/** The invocation as a shell string, e.g. `npx -y @njeybe/nativ`, quoting parts that need it. */
+export function cliString(invocation) {
+    return [invocation.command, ...invocation.prefixArgs].map(quoteIfNeeded).join(' ');
+}
+// ─── Desired settings ──────────────────────────────────────────────────────────────────────────────
+/** Secret files an agent must not read. Mirrors the env files the air-gap protects. */
+const SECRET_READ_DENY = [
+    'Read(./.env)',
+    'Read(./.env.local)',
+    'Read(./.env.development)',
+    'Read(./.env.development.local)',
+    'Read(./.env.production)',
+    'Read(./.env.production.local)',
+    'Read(./**/*.pem)',
+    'Read(./**/*.key)',
+];
+export function buildDesiredConfig(invocation) {
+    const cli = cliString(invocation);
+    const prefixes = [...new Set([cli, 'nativ'])];
+    return {
+        cli,
+        mcpServer: { command: invocation.command, args: [...invocation.prefixArgs, 'mcp'] },
+        allow: [`Bash(${cli} *)`, `mcp__${MCP_SERVER_NAME}__*`],
+        // Deny beats allow, so the broad `nativ *` allow cannot be used to lift a guardrail or write a contract.
+        deny: [
+            ...prefixes.flatMap((p) => [
+                `Bash(${p} task unlock *)`,
+                `Bash(${p} db sync *)`,
+                `Bash(${p} task complete * --no-verify)`,
+                `Bash(${p} task complete * --no-verify *)`,
+            ]),
+            ...SECRET_READ_DENY,
+        ],
+        // Contract edits always need a human's yes, whichever agent asks.
+        ask: ['Edit(./.ai/**)', 'Write(./.ai/**)'],
+        preToolUse: { matcher: PRE_TOOL_USE_MATCHER, command: `${cli} hook check`, timeout: HOOK_TIMEOUT_SECONDS },
+        sessionStart: { matcher: SESSION_START_MATCHER, command: `${cli} hook context`, timeout: HOOK_TIMEOUT_SECONDS },
+    };
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function unionStrings(existing, wanted) {
+    const list = Array.isArray(existing) ? existing.filter((v) => typeof v === 'string') : [];
+    const added = wanted.filter((w) => !list.includes(w));
+    return { list: [...list, ...added], added };
+}
+const isNativHookCommand = (command, kind) => typeof command === 'string' && new RegExp(`\\bhook ${kind}\\b`).test(command) && /nativ|cli\.js/.test(command);
+/** Updates our hook in place when there is one, appends a group when there is not, leaves every other group alone. */
+function mergeHook(groups, kind, want) {
+    const list = Array.isArray(groups) ? groups.filter(isObject) : [];
+    const desiredHook = { type: 'command', command: want.command, timeout: want.timeout };
+    for (const group of list) {
+        const hooks = Array.isArray(group.hooks) ? group.hooks : [];
+        const index = hooks.findIndex((h) => isNativHookCommand(h?.command, kind));
+        if (index === -1)
+            continue;
+        const before = JSON.stringify([group.matcher, hooks[index]]);
+        group.matcher = want.matcher;
+        hooks[index] = { ...hooks[index], ...desiredHook };
+        group.hooks = hooks;
+        return { groups: list, changed: JSON.stringify([group.matcher, hooks[index]]) !== before };
+    }
+    list.push({ matcher: want.matcher, hooks: [desiredHook] });
+    return { groups: list, changed: true };
+}
+export function mergeClaudeSettings(existing, desired) {
+    const merged = { ...existing };
+    const changes = [];
+    const warnings = [];
+    const permissions = isObject(merged.permissions) ? { ...merged.permissions } : {};
+    for (const [key, wanted] of [['allow', desired.allow], ['deny', desired.deny], ['ask', desired.ask]]) {
+        const { list, added } = unionStrings(permissions[key], wanted);
+        if (added.length) {
+            permissions[key] = list;
+            changes.push(`permissions.${key}: +${added.length}`);
+        }
+    }
+    merged.permissions = permissions;
+    const hooks = isObject(merged.hooks) ? { ...merged.hooks } : {};
+    const pre = mergeHook(hooks.PreToolUse, 'check', desired.preToolUse);
+    hooks.PreToolUse = pre.groups;
+    if (pre.changed)
+        changes.push('hooks.PreToolUse (nativ hook check)');
+    const start = mergeHook(hooks.SessionStart, 'context', desired.sessionStart);
+    hooks.SessionStart = start.groups;
+    if (start.changed)
+        changes.push('hooks.SessionStart (nativ hook context)');
+    merged.hooks = hooks;
+    const enabled = unionStrings(merged.enabledMcpjsonServers, [MCP_SERVER_NAME]);
+    if (enabled.added.length) {
+        merged.enabledMcpjsonServers = enabled.list;
+        changes.push('enabledMcpjsonServers: +nativ');
+    }
+    if (Array.isArray(merged.disabledMcpjsonServers) && merged.disabledMcpjsonServers.includes(MCP_SERVER_NAME)) {
+        warnings.push(`.claude/settings.json disables the "${MCP_SERVER_NAME}" MCP server; leaving that choice alone.`);
+    }
+    return { merged, changes, warnings };
+}
+export function mergeMcpConfig(existing, desired) {
+    const servers = isObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
+    const current = servers[MCP_SERVER_NAME];
+    const want = { command: desired.mcpServer.command, args: desired.mcpServer.args };
+    const same = isObject(current) && current.command === want.command && JSON.stringify(current.args) === JSON.stringify(want.args);
+    if (!same)
+        servers[MCP_SERVER_NAME] = isObject(current) ? { ...current, ...want } : want;
+    return { merged: { ...existing, mcpServers: servers }, changed: !same };
+}
+// ─── Managed markdown files ────────────────────────────────────────────────────────────────────────
+const shortHash = (text) => crypto.createHash('sha256').update(text).digest('hex').slice(0, 12);
+/** CRLF and a leading BOM to plain LF. */
+export const toLf = (text) => text.replace(/^/, '').replace(/\r\n/g, '\n');
+/** Appends the marker that lets a later run tell "nativ wrote this, untouched" from "a person edited this". */
+export function stampManaged(content) {
+    // Always LF: a Windows checkout (core.autocrlf) or an editor may hand us CRLF, and neither is an edit.
+    const body = toLf(content).replace(/\s+$/, '');
+    return `${body}\n\n${MANAGED_PREFIX}${shortHash(body)} -->\n`;
+}
+export function managedState(content) {
+    const lf = toLf(content);
+    const match = MANAGED_PATTERN.exec(lf);
+    if (!match)
+        return 'unmanaged';
+    const body = lf.slice(0, match.index).replace(/\s+$/, '');
+    return shortHash(body) === match[1] ? 'pristine' : 'modified';
+}
+/**
+ * Decides what to do with a file derived from a template (a directive or a role guide).
+ * Missing files are created; files nativ wrote and nobody edited (marker intact, or matching a template nativ
+ * shipped before markers existed) follow the template; anything edited by hand is kept unless `force` is set.
+ * `legacyKey` names the file in LEGACY_TEMPLATE_HASHES.
+ */
+export function planTemplateFile(existing, template, legacyKey, force = false) {
+    const next = stampManaged(template);
+    if (existing === null)
+        return { action: 'created', content: next };
+    if (existing === next)
+        return { action: 'unchanged' };
+    const state = managedState(existing);
+    if (state === 'pristine')
+        return { action: 'updated', detail: 'template updated', content: next };
+    if (state === 'unmanaged') {
+        if (normalizeForHash(existing) === normalizeForHash(template))
+            return { action: 'updated', detail: 'now tracked by nativ', content: next };
+        if (isLegacyTemplate(legacyKey, existing))
+            return { action: 'updated', detail: 'refreshed from an earlier nativ template', content: next };
+    }
+    if (force)
+        return { action: 'updated', detail: 'forced', content: next };
+    return {
+        action: 'skipped',
+        detail: state === 'modified'
+            ? 'edited by hand (use --force to replace)'
+            : 'not an untouched nativ template, so treated as edited by hand (use --force to replace)',
+    };
+}
+// ─── Planning ──────────────────────────────────────────────────────────────────────────────────────
+export function getTemplatesDir() {
+    const candidate = path.resolve(__dirname, '..', '..', 'templates');
+    return fs.existsSync(candidate) ? candidate : path.resolve(__dirname, '..', 'templates');
+}
+function readText(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function serializeJson(value) {
+    return JSON.stringify(value, null, 2) + '\n';
+}
+/**
+ * The command already registered for the nativ MCP server in `.mcp.json`, when it has the shape setup writes
+ * (`<command> <args...> mcp`). Reusing it keeps hooks and permissions in step with what the project chose, so a
+ * plain `nativ setup` or `nativ doctor --fix` never silently swaps a deliberate `--command` for auto-detection.
+ */
+export function configuredInvocation(root) {
+    const text = readText(path.join(root, '.mcp.json'));
+    if (text === null)
+        return null;
+    try {
+        const parsed = parseJsonLoose(text);
+        const server = isObject(parsed) && isObject(parsed.mcpServers) ? parsed.mcpServers[MCP_SERVER_NAME] : undefined;
+        if (!isObject(server) || typeof server.command !== 'string' || !server.command.trim())
+            return null;
+        const args = Array.isArray(server.args) ? server.args : [];
+        if (args.length === 0 || args[args.length - 1] !== 'mcp' || !args.every((a) => typeof a === 'string'))
+            return null;
+        const prefixArgs = args.slice(0, -1);
+        return { command: server.command, prefixArgs, portable: ![server.command, ...prefixArgs].some((p) => path.isAbsolute(p)) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Computes what `nativ setup` would do, without touching disk. */
+export function planSetup(rootArg, options = {}) {
+    const root = path.resolve(rootArg);
+    const invocation = options.command?.trim()
+        ? resolveCliInvocation({ command: options.command, hasBinary: options.hasBinary })
+        : configuredInvocation(root) ?? resolveCliInvocation({ hasBinary: options.hasBinary });
+    const desired = buildDesiredConfig(invocation);
+    const templatesDir = options.templatesDir ?? getTemplatesDir();
+    const changes = [];
+    const warnings = [];
+    const writes = new Map();
+    if (!invocation.portable) {
+        warnings.push('nativ is not on PATH, so the generated config points at this machine\'s install. ' +
+            'Install it globally (npm i -g @njeybe/nativ) or pass --command "npx -y @njeybe/nativ" so the config works for your team.');
+    }
+    const record = (rel, existing, next, detail) => {
+        if (existing === null) {
+            changes.push({ path: rel, action: 'created', detail });
+            writes.set(rel, next);
+        }
+        else if (existing === next) {
+            changes.push({ path: rel, action: 'unchanged' });
+        }
+        else {
+            changes.push({ path: rel, action: 'updated', detail });
+            writes.set(rel, next);
+        }
+    };
+    const skip = (rel, detail) => {
+        changes.push({ path: rel, action: 'skipped', detail });
+        warnings.push(`${rel}: ${detail}`);
+    };
+    /** Reads a JSON file for merging. Returns null (after recording a skip) when it exists but is not valid JSON. */
+    const readJsonObject = (rel) => {
+        const text = readText(path.join(root, rel));
+        if (text === null || !text.trim())
+            return { text, value: {} };
+        try {
+            const parsed = parseJsonLoose(text);
+            if (isObject(parsed))
+                return { text, value: parsed };
+        }
+        catch {
+            // Fall through.
+        }
+        skip(rel, 'exists but is not a valid JSON object; not modified. Fix or delete it and re-run.');
+        return null;
+    };
+    // .mcp.json
+    const mcp = readJsonObject('.mcp.json');
+    if (mcp) {
+        const { merged, changed } = mergeMcpConfig(mcp.value, desired);
+        record('.mcp.json', mcp.text, changed || mcp.text === null ? serializeJson(merged) : mcp.text, changed ? `${MCP_SERVER_NAME} server -> ${desired.cli} mcp` : undefined);
+    }
+    // .claude/settings.json
+    const settings = readJsonObject('.claude/settings.json');
+    if (settings) {
+        const { merged, changes: settingChanges, warnings: settingWarnings } = mergeClaudeSettings(settings.value, desired);
+        warnings.push(...settingWarnings);
+        record('.claude/settings.json', settings.text, settingChanges.length || settings.text === null ? serializeJson(merged) : (settings.text ?? ''), settingChanges.join('; ') || undefined);
+    }
+    // .claude/agents/*.md: written only when missing, pristine, or forced
+    for (const file of AGENT_FILES) {
+        const rel = `.claude/agents/${file}`;
+        const template = readText(path.join(templatesDir, 'claude-agents', file));
+        if (template === null) {
+            skip(rel, `template templates/claude-agents/${file} is missing from this nativ install.`);
+            continue;
+        }
+        const next = stampManaged(template);
+        const existing = readText(path.join(root, rel));
+        if (existing === null || existing === next) {
+            record(rel, existing, next);
+            continue;
+        }
+        const state = managedState(existing);
+        if (state === 'pristine' || options.force)
+            record(rel, existing, next, state === 'pristine' ? 'template updated' : 'forced');
+        else
+            skip(rel, state === 'modified' ? 'was edited by hand; not overwritten (use --force to replace).' : 'exists and is not managed by nativ; not overwritten (use --force to replace).');
+    }
+    // AGENTS.md is the canonical directive; CLAUDE.md and GEMINI.md only ever get a pointer, and only when absent
+    const agents = readText(path.join(templatesDir, 'AGENTS.md'));
+    if (agents === null) {
+        skip('AGENTS.md', 'template templates/AGENTS.md is missing from this nativ install.');
+    }
+    else {
+        const next = stampManaged(agents);
+        const existing = readText(path.join(root, 'AGENTS.md'));
+        if (existing === null || existing === next)
+            record('AGENTS.md', existing, next);
+        else if (managedState(existing) === 'pristine' || options.force)
+            record('AGENTS.md', existing, next, 'template updated');
+        else
+            skip('AGENTS.md', 'exists and was not written by nativ (or was edited); not overwritten (use --force to replace).');
+    }
+    for (const [file, title] of [['CLAUDE.md', 'Claude Code'], ['GEMINI.md', 'Gemini / Antigravity']]) {
+        const existing = readText(path.join(root, file));
+        if (existing === null)
+            record(file, null, `# ${title} directive\n\n@AGENTS.md\n`);
+        else
+            changes.push({ path: file, action: 'unchanged', detail: /AGENTS\.md/.test(existing) ? undefined : 'exists; does not reference AGENTS.md' });
+    }
+    // .nativ/config.json
+    const config = readJsonObject('.nativ/config.json');
+    if (config) {
+        const next = { ...config.value };
+        let detail;
+        if (options.enforcement && next.enforcement !== options.enforcement) {
+            next.enforcement = options.enforcement;
+            detail = `enforcement=${options.enforcement}`;
+        }
+        else if (next.enforcement === undefined) {
+            next.enforcement = loadEnforcementMode(root);
+            detail = `enforcement=${String(next.enforcement)}`;
+        }
+        record('.nativ/config.json', config.text, detail || config.text === null ? serializeJson(next) : (config.text ?? ''), detail);
+    }
+    return { root, invocation, changes, warnings, writes };
+}
+/** Writes the planned differences. Idempotent: applying twice changes nothing the second time. */
+export function applySetup(rootArg, options = {}) {
+    const plan = planSetup(rootArg, options);
+    if (!options.dryRun) {
+        for (const [rel, content] of plan.writes) {
+            const file = path.join(plan.root, rel);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            const tmp = `${file}.${process.pid}.tmp`;
+            fs.writeFileSync(tmp, content, 'utf8');
+            fs.renameSync(tmp, file);
+        }
+    }
+    return { root: plan.root, dryRun: options.dryRun === true, invocation: plan.invocation, changes: plan.changes, warnings: plan.warnings };
+}
+function readPlanTasks(root) {
+    try {
+        const plan = parseJsonLoose(fs.readFileSync(path.join(root, '.ai', 'master_plan.json'), 'utf8'));
+        const tasks = [];
+        for (const milestone of plan.milestones ?? []) {
+            for (const t of milestone.tasks ?? []) {
+                if (typeof t.id === 'string') {
+                    tasks.push({
+                        id: t.id,
+                        title: typeof t.title === 'string' ? t.title : '',
+                        status: typeof t.status === 'string' ? t.status : 'pending',
+                        dependencies: Array.isArray(t.dependencies) ? t.dependencies : [],
+                        targetFiles: Array.isArray(t.targetFiles) ? t.targetFiles : [],
+                    });
+                }
+            }
+        }
+        return tasks;
+    }
+    catch {
+        return [];
+    }
+}
+/** A few lines of orientation for a new Claude Code session, or null when this is not a nativ project. */
+export function buildSessionContext(cwd, env = process.env) {
+    const root = resolveProjectRoot(cwd);
+    if (!fs.existsSync(path.join(root, '.ai', 'master_plan.json')))
+        return null;
+    const tasks = readPlanTasks(root);
+    const active = tasks.filter((t) => t.status === 'in_progress');
+    const done = new Set(tasks.filter((t) => t.status === 'completed').map((t) => t.id));
+    const next = tasks.find((t) => t.status === 'pending' && t.dependencies.every((d) => done.has(d)));
+    const role = (env[ROLE_ENV] ?? '').trim().toLowerCase() || 'project manager';
+    const lines = [
+        'This is a nativ project (role-based multi-agent workflow).',
+        `Session role: ${role}. Enforcement: ${loadEnforcementMode(root)}. Edits outside the active task's targetFiles are flagged, and .ai/ contracts are architect-only.`,
+    ];
+    if (active.length) {
+        for (const t of active)
+            lines.push(`In progress: ${t.id} "${t.title}" (targetFiles: ${t.targetFiles.join(', ') || 'none'})`);
+    }
+    else if (next) {
+        lines.push(`Next available task: ${next.id} "${next.title}". Run \`nativ task next\` to load its context.`);
+    }
+    else {
+        lines.push('No task is in progress or ready.');
+    }
+    lines.push('Prefer the nativ_* MCP tools (or the `nativ` CLI). Do not edit .ai/ directly: escalate contract gaps with `nativ task escalate`.');
+    return lines.join('\n');
+}
+/** `nativ hook context`: prints the SessionStart hook output. Never throws and always prints valid JSON or nothing. */
+export function runSessionContext(targetDirArg, write = (t) => process.stdout.write(t)) {
+    try {
+        const context = buildSessionContext(targetDirArg ? path.resolve(targetDirArg) : process.env.CLAUDE_PROJECT_DIR || process.cwd());
+        if (context)
+            write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context } }));
+    }
+    catch {
+        // Orientation is a convenience; a failure must never disturb session start.
+    }
+}

package/dist/core/telemetry.d.ts

@@ -0,0 +1,156 @@
+import { MasterPlanTask } from '../scanner/types.js';
+import { VerificationResult } from './verifier.js';
+export interface TokenEstimate {
+    inputEstimated: number;
+    outputEstimated: number;
+    totalEstimated: number;
+    costUsdEstimated: number;
+}
+export interface TaskTelemetryRecord {
+    taskId: string;
+    title: string;
+    assignedSubagent: string;
+    startedAt: string;
+    completedAt?: string;
+    durationMs: number;
+    status: 'in_progress' | 'completed' | 'failed' | 'blocked';
+    verification?: {
+        command: string;
+        durationMs: number;
+        exitCode: number;
+        skipped: boolean;
+    };
+    tokens?: TokenEstimate;
+    /** Grounded usage reported by the Messages API across every native run of this task. */
+    actualUsage?: ActualTokenUsage;
+    notes?: string;
+}
+/**
+ * Token counts reported by the Messages API (`response.usage`), accumulated
+ * across agent turns. `inputTokens` excludes cached tokens, matching the API.
+ */
+export interface ActualTokenUsage {
+    model: string;
+    turns: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    /** Subset of `outputTokens` spent on internal reasoning (0 when not reported). */
+    thinkingTokens: number;
+    costUsd: number;
+}
+export interface TelemetrySummary {
+    totalTasksCompleted: number;
+    totalDurationMs: number;
+    estimatedTotalTokens: number;
+    estimatedTotalCostUsd: number;
+    verificationPassRate: number;
+    totalVerificationsRun: number;
+    totalVerificationsPassed: number;
+    circuitBreakerTrips: number;
+    /** Total role-enforcement violations recorded, including ones that aged out of `violations`. */
+    roleViolations?: number;
+    /** Grounded spend across all native runs, including failed ones (billing is billing). */
+    actualSpendUsd?: number;
+    actualInputTokens?: number;
+    actualOutputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    thinkingTokens?: number;
+    /** cacheRead / (input + cacheRead + cacheCreation), in [0, 1]. */
+    cacheHitRate?: number;
+}
+/** One write that left its role: an out-of-scope edit, a contract edit by a non-architect, or a secret file. */
+export interface RoleViolationRecord {
+    at: string;
+    rule: 'protected_path' | 'secret_path' | 'out_of_scope';
+    /** `warn` was logged and allowed; `block` was denied. */
+    mode: 'warn' | 'block';
+    tool: string;
+    /** Project-relative path with forward slashes. */
+    path: string;
+    taskIds: string[];
+}
+/** Oldest entries are dropped past this, so a chatty agent cannot grow telemetry.json without bound. */
+export declare const MAX_ROLE_VIOLATIONS = 200;
+export interface ProjectTelemetry {
+    $schema?: string;
+    version: string;
+    projectName: string;
+    lastUpdated: string;
+    modelTierDefault: string;
+    summary: TelemetrySummary;
+    tasks: TaskTelemetryRecord[];
+    violations?: RoleViolationRecord[];
+}
+/** Model whose rates price heuristic estimates; matches the native engine's default model. */
+export declare const DEFAULT_TELEMETRY_MODEL = "claude-opus-5-5";
+/** List price of DEFAULT_TELEMETRY_MODEL; also the fallback for models missing from MODEL_PRICING. */
+export declare const INPUT_TOKEN_COST_PER_M = 4;
+export declare const OUTPUT_TOKEN_COST_PER_M = 20;
+export interface ModelPricing {
+    inputPerM: number;
+    outputPerM: number;
+    /** 5-minute ephemeral cache writes. */
+    cacheWritePerM: number;
+    cacheReadPerM: number;
+}
+/** First-party Claude API list prices in USD per 1M tokens. */
+export declare const MODEL_PRICING: Readonly<Record<string, ModelPricing>>;
+/** True when MODEL_PRICING knows the model (exactly or as a dated / suffixed variant). */
+export declare function isPricedModel(model: unknown): model is string;
+/** Resolves pricing by exact ID, then by longest known prefix (e.g. dated or `-fast` variants). */
+export declare function resolveModelPricing(model: string): ModelPricing;
+/** Prices one usage slice with the model's input, output, cache-write and cache-read rates. */
+export declare function computeActualCostUsd(model: string, usage: Pick<ActualTokenUsage, 'inputTokens' | 'outputTokens' | 'cacheCreationTokens' | 'cacheReadTokens'>): number;
+export declare function emptyActualUsage(model: string): ActualTokenUsage;
+/** Sums two usage records; the result keeps `a.model` unless `a` is empty. */
+export declare function mergeActualUsage(a: ActualTokenUsage, b: ActualTokenUsage): ActualTokenUsage;
+export declare function cacheHitRate(usage: Pick<ActualTokenUsage, 'inputTokens' | 'cacheCreationTokens' | 'cacheReadTokens'>): number;
+/** Prices estimated input/output tokens at a model's list rates. */
+export declare function priceEstimate(model: string, inputEstimated: number, outputEstimated: number): number;
+/**
+ * Calculates estimated tokens and cost based on contract slice, target files, and diff heuristics.
+ */
+export declare function estimateTokens(targetDir: string, task: MasterPlanTask, model?: string): TokenEstimate;
+/**
+ * Loads project telemetry from .ai/telemetry.json or returns a fresh initialized state.
+ */
+export declare function loadTelemetry(telemetryPath: string, projectName?: string): ProjectTelemetry;
+/**
+ * Atomically writes telemetry to disk with Windows EPERM resilience.
+ */
+export declare function saveTelemetry(telemetryPath: string, telemetry: ProjectTelemetry): boolean;
+/**
+ * Recomputes aggregate summary metrics across all recorded tasks.
+ */
+export declare function recomputeTelemetrySummary(telemetry: ProjectTelemetry): void;
+/**
+ * Records the start of an agent task in .ai/telemetry.json.
+ */
+export declare function recordTaskStart(targetDir: string, task: MasterPlanTask): Promise<void>;
+/**
+ * Records completion of an agent task, tracking duration, verification results, tokens, and cost.
+ */
+export declare function recordTaskComplete(targetDir: string, task: MasterPlanTask, verificationResult?: VerificationResult | null, notes?: string): Promise<TaskTelemetryRecord | null>;
+/**
+ * Folds one native run's API-reported usage into the task's grounded telemetry.
+ * Creates the task record when the run was dispatched without `nativ task start`.
+ */
+export declare function recordRunnerUsage(targetDir: string, task: Pick<MasterPlanTask, 'id' | 'title' | 'assignedSubagent'>, usage: ActualTokenUsage): Promise<TaskTelemetryRecord>;
+/**
+ * Logs a role-enforcement violation to .ai/telemetry.json. Best effort: it never throws, because the
+ * hook that calls it must not fail an agent's tool call over bookkeeping.
+ */
+export declare function recordRoleViolation(targetDir: string, violation: Omit<RoleViolationRecord, 'at'>): Promise<void>;
+/**
+ * Increments circuit breaker trips counter in telemetry.
+ */
+export declare function recordCircuitBreakerTrip(targetDir: string, taskId: string): Promise<void>;
+/**
+ * Returns formatted telemetry dashboard summary lines for CLI display.
+ */
+export declare function formatTelemetrySummary(telemetry: ProjectTelemetry, plan?: {
+    completedTasks: number;
+}): string;