@njeybe/nativ 2.5.1 → 2.6.0

package/dist/db/introspector.js

@@ -1,6 +1,7 @@
 import { performance } from 'node:perf_hooks';
 import { isNoSqlEngine } from './types.js';
 import { databaseNameFromUrl, detectEngine, maskConnectionString, MASK, parseFirestoreUrl, redactMediaUrl, sqlitePathFromUrl, } from './env-parser.js';
+import { loadSqlite } from './sqlite.js';
 /**
  * Multi-engine schema introspector.
  * Reads structural metadata only (tables, columns, types, nullability, keys, indexes).
@@ -81,30 +82,30 @@ async function createPostgresDriver(url) {
         },
         async tables() {
             const builder = new TableBuilder();
-            const tables = await client.query(`
-        SELECT t.table_name, obj_description(format('%I.%I', t.table_schema, t.table_name)::regclass, 'pg_class') AS description
-        FROM information_schema.tables t
-        WHERE t.table_schema = current_schema() AND t.table_type = 'BASE TABLE'
+            const tables = await client.query(`
+        SELECT t.table_name, obj_description(format('%I.%I', t.table_schema, t.table_name)::regclass, 'pg_class') AS description
+        FROM information_schema.tables t
+        WHERE t.table_schema = current_schema() AND t.table_type = 'BASE TABLE'
         ORDER BY t.table_name`);
             for (const row of tables.rows) {
                 const table = builder.get(row.table_name);
                 if (row.description)
                     table.description = row.description;
             }
-            const pks = await client.query(`
-        SELECT kcu.table_name, kcu.column_name
-        FROM information_schema.table_constraints tc
-        JOIN information_schema.key_column_usage kcu
-          ON kcu.constraint_name = tc.constraint_name AND kcu.table_schema = tc.table_schema AND kcu.table_name = tc.table_name
+            const pks = await client.query(`
+        SELECT kcu.table_name, kcu.column_name
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON kcu.constraint_name = tc.constraint_name AND kcu.table_schema = tc.table_schema AND kcu.table_name = tc.table_name
         WHERE tc.table_schema = current_schema() AND tc.constraint_type = 'PRIMARY KEY'`);
             const pkSet = new Set(pks.rows.map((r) => `${r.table_name}.${r.column_name}`));
-            const columns = await client.query(`
-        SELECT c.table_name, c.column_name, c.data_type, c.udt_name, c.character_maximum_length,
-               c.numeric_precision, c.numeric_scale, c.is_nullable, c.column_default
-        FROM information_schema.columns c
-        JOIN information_schema.tables t
-          ON t.table_schema = c.table_schema AND t.table_name = c.table_name AND t.table_type = 'BASE TABLE'
-        WHERE c.table_schema = current_schema()
+            const columns = await client.query(`
+        SELECT c.table_name, c.column_name, c.data_type, c.udt_name, c.character_maximum_length,
+               c.numeric_precision, c.numeric_scale, c.is_nullable, c.column_default
+        FROM information_schema.columns c
+        JOIN information_schema.tables t
+          ON t.table_schema = c.table_schema AND t.table_name = c.table_name AND t.table_type = 'BASE TABLE'
+        WHERE c.table_schema = current_schema()
         ORDER BY c.table_name, c.ordinal_position`);
             for (const row of columns.rows) {
                 builder.get(row.table_name).columns.push({
@@ -116,31 +117,31 @@ async function createPostgresDriver(url) {
                 });
             }
             // information_schema has no index view — pg_catalog is the only source.
-            const indexes = await client.query(`
-        SELECT t.relname AS table_name, i.relname AS index_name, ix.indisunique AS is_unique,
-               (SELECT array_agg(a.attname::text ORDER BY k.ord)
-                  FROM unnest(ix.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord)
-                  JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum) AS columns
-        FROM pg_index ix
-        JOIN pg_class t ON t.oid = ix.indrelid
-        JOIN pg_class i ON i.oid = ix.indexrelid
-        JOIN pg_namespace n ON n.oid = t.relnamespace
-        WHERE n.nspname = current_schema() AND NOT ix.indisprimary AND t.relkind IN ('r', 'p')
+            const indexes = await client.query(`
+        SELECT t.relname AS table_name, i.relname AS index_name, ix.indisunique AS is_unique,
+               (SELECT array_agg(a.attname::text ORDER BY k.ord)
+                  FROM unnest(ix.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord)
+                  JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum) AS columns
+        FROM pg_index ix
+        JOIN pg_class t ON t.oid = ix.indrelid
+        JOIN pg_class i ON i.oid = ix.indexrelid
+        JOIN pg_namespace n ON n.oid = t.relnamespace
+        WHERE n.nspname = current_schema() AND NOT ix.indisprimary AND t.relkind IN ('r', 'p')
         ORDER BY t.relname, i.relname`);
             for (const row of indexes.rows) {
                 builder.get(row.table_name).indexes.push({ name: row.index_name, columns: row.columns ?? [], unique: row.is_unique });
             }
-            const fks = await client.query(`
-        SELECT con.conname AS constraint_name, cl.relname AS table_name, a.attname AS column_name,
-               fcl.relname AS ref_table, fa.attname AS ref_column, con.confdeltype AS on_delete
-        FROM pg_constraint con
-        JOIN pg_class cl ON cl.oid = con.conrelid
-        JOIN pg_namespace n ON n.oid = cl.relnamespace
-        JOIN pg_class fcl ON fcl.oid = con.confrelid
-        CROSS JOIN LATERAL unnest(con.conkey, con.confkey) AS k(attnum, fattnum)
-        JOIN pg_attribute a ON a.attrelid = con.conrelid AND a.attnum = k.attnum
-        JOIN pg_attribute fa ON fa.attrelid = con.confrelid AND fa.attnum = k.fattnum
-        WHERE n.nspname = current_schema() AND con.contype = 'f'
+            const fks = await client.query(`
+        SELECT con.conname AS constraint_name, cl.relname AS table_name, a.attname AS column_name,
+               fcl.relname AS ref_table, fa.attname AS ref_column, con.confdeltype AS on_delete
+        FROM pg_constraint con
+        JOIN pg_class cl ON cl.oid = con.conrelid
+        JOIN pg_namespace n ON n.oid = cl.relnamespace
+        JOIN pg_class fcl ON fcl.oid = con.confrelid
+        CROSS JOIN LATERAL unnest(con.conkey, con.confkey) AS k(attnum, fattnum)
+        JOIN pg_attribute a ON a.attrelid = con.conrelid AND a.attnum = k.attnum
+        JOIN pg_attribute fa ON fa.attrelid = con.confrelid AND fa.attnum = k.fattnum
+        WHERE n.nspname = current_schema() AND con.contype = 'f'
         ORDER BY cl.relname, con.conname`);
             for (const row of fks.rows) {
                 builder.get(row.table_name).foreignKeys.push({
@@ -177,22 +178,22 @@ async function createMysqlDriver(url) {
         },
         async tables() {
             const builder = new TableBuilder();
-            for (const row of await rows(`
-        SELECT TABLE_NAME AS table_name, TABLE_COMMENT AS table_comment
-        FROM information_schema.TABLES
-        WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
+            for (const row of await rows(`
+        SELECT TABLE_NAME AS table_name, TABLE_COMMENT AS table_comment
+        FROM information_schema.TABLES
+        WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
         ORDER BY TABLE_NAME`)) {
                 const table = builder.get(row.table_name);
                 if (row.table_comment)
                     table.description = row.table_comment;
             }
-            for (const row of await rows(`
-        SELECT c.TABLE_NAME AS table_name, c.COLUMN_NAME AS column_name, c.COLUMN_TYPE AS column_type,
-               c.IS_NULLABLE AS is_nullable, c.COLUMN_DEFAULT AS column_default, c.COLUMN_KEY AS column_key
-        FROM information_schema.COLUMNS c
-        JOIN information_schema.TABLES t
-          ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME AND t.TABLE_TYPE = 'BASE TABLE'
-        WHERE c.TABLE_SCHEMA = DATABASE()
+            for (const row of await rows(`
+        SELECT c.TABLE_NAME AS table_name, c.COLUMN_NAME AS column_name, c.COLUMN_TYPE AS column_type,
+               c.IS_NULLABLE AS is_nullable, c.COLUMN_DEFAULT AS column_default, c.COLUMN_KEY AS column_key
+        FROM information_schema.COLUMNS c
+        JOIN information_schema.TABLES t
+          ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME AND t.TABLE_TYPE = 'BASE TABLE'
+        WHERE c.TABLE_SCHEMA = DATABASE()
         ORDER BY c.TABLE_NAME, c.ORDINAL_POSITION`)) {
                 builder.get(row.table_name).columns.push({
                     name: row.column_name,
@@ -203,10 +204,10 @@ async function createMysqlDriver(url) {
                 });
             }
             const indexMap = new Map();
-            for (const row of await rows(`
-        SELECT TABLE_NAME AS table_name, INDEX_NAME AS index_name, NON_UNIQUE AS non_unique, COLUMN_NAME AS column_name
-        FROM information_schema.STATISTICS
-        WHERE TABLE_SCHEMA = DATABASE() AND INDEX_NAME <> 'PRIMARY'
+            for (const row of await rows(`
+        SELECT TABLE_NAME AS table_name, INDEX_NAME AS index_name, NON_UNIQUE AS non_unique, COLUMN_NAME AS column_name
+        FROM information_schema.STATISTICS
+        WHERE TABLE_SCHEMA = DATABASE() AND INDEX_NAME <> 'PRIMARY'
         ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX`)) {
                 const key = `${row.table_name}.${row.index_name}`;
                 let entry = indexMap.get(key);
@@ -219,13 +220,13 @@ async function createMysqlDriver(url) {
             }
             for (const { table, index } of indexMap.values())
                 builder.get(table).indexes.push(index);
-            for (const row of await rows(`
-        SELECT k.CONSTRAINT_NAME AS constraint_name, k.TABLE_NAME AS table_name, k.COLUMN_NAME AS column_name,
-               k.REFERENCED_TABLE_NAME AS ref_table, k.REFERENCED_COLUMN_NAME AS ref_column, r.DELETE_RULE AS delete_rule
-        FROM information_schema.KEY_COLUMN_USAGE k
-        JOIN information_schema.REFERENTIAL_CONSTRAINTS r
-          ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME AND r.TABLE_NAME = k.TABLE_NAME
-        WHERE k.TABLE_SCHEMA = DATABASE() AND k.REFERENCED_TABLE_NAME IS NOT NULL
+            for (const row of await rows(`
+        SELECT k.CONSTRAINT_NAME AS constraint_name, k.TABLE_NAME AS table_name, k.COLUMN_NAME AS column_name,
+               k.REFERENCED_TABLE_NAME AS ref_table, k.REFERENCED_COLUMN_NAME AS ref_column, r.DELETE_RULE AS delete_rule
+        FROM information_schema.KEY_COLUMN_USAGE k
+        JOIN information_schema.REFERENTIAL_CONSTRAINTS r
+          ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME AND r.TABLE_NAME = k.TABLE_NAME
+        WHERE k.TABLE_SCHEMA = DATABASE() AND k.REFERENCED_TABLE_NAME IS NOT NULL
         ORDER BY k.TABLE_NAME, k.CONSTRAINT_NAME, k.ORDINAL_POSITION`)) {
                 builder.get(row.table_name).foreignKeys.push({
                     name: row.constraint_name,
@@ -247,7 +248,7 @@ function quoteIdent(name) {
     return `"${name.replace(/"/g, '""')}"`;
 }
 async function createSqliteDriver(url) {
-    const { DatabaseSync } = await import('node:sqlite');
+    const { DatabaseSync } = await loadSqlite();
     const filePath = sqlitePathFromUrl(url);
     // readOnly: never create a database file or mutate one while introspecting.
     const db = filePath === ':memory:' ? new DatabaseSync(':memory:') : new DatabaseSync(filePath, { readOnly: true });

package/dist/db/sqlite.d.ts

@@ -0,0 +1,3 @@
+/** `node:sqlite` ships with Node.js 22.5+; nativ itself supports Node 20, so SQLite projects get a clear message there. */
+export declare const SQLITE_MIN_NODE = "22.5";
+export declare function loadSqlite(): Promise<typeof import('node:sqlite')>;

package/dist/db/sqlite.js

@@ -0,0 +1,10 @@
+/** `node:sqlite` ships with Node.js 22.5+; nativ itself supports Node 20, so SQLite projects get a clear message there. */
+export const SQLITE_MIN_NODE = '22.5';
+export async function loadSqlite() {
+    try {
+        return await import('node:sqlite');
+    }
+    catch {
+        throw new Error(`SQLite databases need Node.js ${SQLITE_MIN_NODE} or newer (this is ${process.version}). Upgrade Node.js, or use Postgres, MySQL or MongoDB.`);
+    }
+}

package/dist/governor/circuit-breaker.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { withPlanLockSync } from '../core/lock-manager.js';
 import { recordCircuitBreakerTrip } from '../core/telemetry.js';
+import { notifyHuman } from '../core/notify.js';
 import { appendEscalation, loadLedger, mutateLedger } from './store.js';
 const MAX_FAILURE_THRESHOLD = 3;
 const newEntry = () => ({ consecutiveFailures: 0, lastFailureTime: '', patchCount: 0 });
@@ -38,6 +39,15 @@ function tryMutateLedger(targetDir, mutator) {
         // Non-fatal
     }
 }
+/** Fire-and-forget: the verdict is synchronous, and an open request keeps a CLI process alive until it settles. */
+function notifyTrip(targetDir, taskId, escalationId, ruleId) {
+    notifyHuman(targetDir, {
+        event: 'circuit_breaker_tripped',
+        taskId,
+        escalationId,
+        summary: `Task ${taskId} failed ${MAX_FAILURE_THRESHOLD} times in a row (${ruleId}) and is now blocked`,
+    }).catch(() => { });
+}
 export class CircuitBreaker {
     static getStatus(targetDir, taskId) {
         const ledger = loadLedger(targetDir);
@@ -138,6 +148,7 @@ export class CircuitBreaker {
         }));
         this.blockTask(targetDir, taskId, `Circuit breaker tripped by Governor: ${ruleResult.ruleId} (${escalationId ?? 'escalation not recorded'})`);
         recordCircuitBreakerTrip(targetDir, taskId).catch(() => { });
+        notifyTrip(targetDir, taskId, escalationId ?? undefined, ruleResult.ruleId);
         return { state, escalationId: escalationId ?? undefined, proposal };
     }
     /** Atomic increment under the ledger lock: concurrent failures are all counted. */
@@ -192,6 +203,7 @@ export class CircuitBreaker {
         // 2. Mark task as blocked in .ai/master_plan.json
         this.blockTask(targetDir, taskId, `Circuit breaker tripped by Governor: ${ruleResult.ruleId} (${escalationId})`);
         recordCircuitBreakerTrip(targetDir, taskId).catch(() => { });
+        notifyTrip(targetDir, taskId, escalationId === 'unrecorded' ? undefined : escalationId, ruleResult.ruleId);
         return {
             escalationId,
             taskId,

package/dist/governor/patch-applier.d.ts

@@ -3,6 +3,7 @@ export declare function getContractHash(filePath: string): string | null;
 export declare function appendAuditLog(targetDir: string, entry: AuditLogEntry): void;
 export declare function applyDbPatch(schema: any, patch: ContractPatch): any;
 export declare function applyApiPatch(contracts: any, patch: ContractPatch): any;
+/** False when the write failed; the shared helper retries Windows sharing violations before giving up. */
 export declare function atomicWriteJson(filePath: string, data: any): boolean;
 export declare function contractFileFor(target: ContractPatch['target']): string;
 export declare function applyPatch(contract: any, patch: ContractPatch): any;

package/dist/governor/patch-applier.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { writeJsonAtomicSync } from '../core/lock-manager.js';
 export function getContractHash(filePath) {
     if (!fs.existsSync(filePath))
         return null;
@@ -98,18 +99,13 @@ export function applyApiPatch(contracts, patch) {
     contracts.updatedAt = new Date().toISOString();
     return contracts;
 }
+/** False when the write failed; the shared helper retries Windows sharing violations before giving up. */
 export function atomicWriteJson(filePath, data) {
-    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
     try {
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
-        fs.renameSync(tmpPath, filePath);
+        writeJsonAtomicSync(filePath, data);
         return true;
     }
     catch {
-        if (fs.existsSync(tmpPath)) {
-            fs.rmSync(tmpPath, { force: true });
-        }
         return false;
     }
 }

package/dist/index.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { runInit } from './commands/init.js';
 import { runStatus } from './commands/status.js';
 import { runValidate } from './commands/validate.js';
-import { runTaskList, runTaskNext, runTaskStart, runTaskComplete, runTaskBlock, runTaskEscalate, runTaskAdd, runTaskProposePatch, runTaskUnlock, } from './commands/task.js';
+import { runTaskList, runTaskNext, runTaskStart, runTaskComplete, runTaskBlock, runTaskReclaim, runTaskEscalate, runTaskAdd, runTaskProposePatch, runTaskUnlock, } from './commands/task.js';
 import { runHookCheck, runHookStatus } from './commands/hook.js';
 import { runSetup } from './commands/setup.js';
 import { runDoctor } from './commands/doctor.js';
@@ -15,6 +15,7 @@ import { runVerify } from './commands/verify.js';
 import { runTestGen, TEST_GEN_FRAMEWORK_HELP } from './commands/test-gen.js';
 import { runBench } from './commands/bench.js';
 import { runTriage } from './commands/triage.js';
+import { runNotifyTest } from './commands/notify.js';
 import { runLearnPropose, runLearnDecide, runLearnList } from './commands/learn.js';
 import { runProfileCommand } from './commands/profile.js';
 import { packageVersion } from './core/version.js';
@@ -80,7 +81,8 @@ export function createProgram() {
         .option('-s, --status <status>', 'Filter tasks by status (pending, in_progress, completed, blocked)')
         .option('-m, --milestone <id>', 'Filter tasks by milestone ID or name')
         .option('--fast-path', 'Show only fast-path tasks')
-        .option('--json', 'Output filtered tasks as JSON')
+        .option('--json', 'Output filtered tasks as JSON (a summary per task)')
+        .option('--full', 'With --json, include every task field')
         .action(async (targetDir, options) => {
         await runTaskList(targetDir, options);
     });
@@ -121,7 +123,8 @@ export function createProgram() {
         .option('-s, --status <status>', 'Filter tasks by status (pending, in_progress, completed, blocked)')
         .option('-m, --milestone <id>', 'Filter tasks by milestone ID or name')
         .option('--fast-path', 'Show only fast-path tasks')
-        .option('--json', 'Output filtered tasks as JSON')
+        .option('--json', 'Output filtered tasks as JSON (a summary per task)')
+        .option('--full', 'With --json, include every task field')
         .action(async (targetDir, options) => {
         await runTaskList(targetDir, options);
     });
@@ -151,9 +154,11 @@ export function createProgram() {
     });
     task
         .command('start <taskId> [targetDir]')
-        .description('Mark a task as in_progress')
-        .action(async (taskId, targetDir) => {
-        await runTaskStart(taskId, targetDir);
+        .description('Claim a pending task whose dependencies are done and mark it in_progress')
+        .option('--agent <id>', 'Who claims the task (default: $NATIV_AGENT_ID)')
+        .option('--force', 'Human override: start a blocked task or one with unfinished dependencies')
+        .action(async (taskId, targetDir, options) => {
+        await runTaskStart(taskId, targetDir, { agent: options.agent, force: options.force });
     });
     task
         .command('complete <taskId> [targetDir]')
@@ -178,6 +183,16 @@ export function createProgram() {
         .action(async (taskId, targetDir, options) => {
         await runVerify(taskId, targetDir, options);
     });
+    task
+        .command('reclaim [taskId] [targetDir]')
+        .description('Put in_progress tasks whose agent stopped back to pending (claims older than --older-than hours)')
+        .option('--older-than <hours>', 'Age at which a claim counts as abandoned (default 4)', parseFloat)
+        .option('--dry-run', 'List what would be reclaimed without changing the plan')
+        .option('--force', 'Human override: reclaim the named task even though its claim is fresh')
+        .option('--json', 'Output the result as JSON')
+        .action(async (taskId, targetDir, options) => {
+        await runTaskReclaim(taskId, targetDir, { olderThan: options.olderThan, dryRun: options.dryRun, force: options.force, json: options.json });
+    });
     task
         .command('block <taskId> [targetDir]')
         .description('Mark a task as blocked with a required reason')
@@ -396,6 +411,14 @@ export function createProgram() {
         .action(async (escalationId, targetDir, options) => {
         await runTriage(escalationId, targetDir, options);
     });
+    program
+        .command('notify')
+        .description('Human notifications (webhook or command) for decisions and circuit-breaker trips')
+        .command('test [targetDir]')
+        .description('Send a sample notification through the configured webhook or command')
+        .action(async (targetDir) => {
+        await runNotifyTest(targetDir);
+    });
     program
         .command('mcp [targetDir]')
         .description('Run the native MCP (Model Context Protocol) server over stdio, exposing nativ tools and .ai/ contract resources')

package/dist/mcp/server.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { captureOutput } from './capture.js';
 export { registerMcpResources, MCP_RESOURCES } from './resources.js';
-export declare const ESCALATION_TYPES: readonly ["contract_drift", "schema_flaw", "missing_credential", "dependency_conflict", "architectural_ambiguity"];
+export { ESCALATION_TYPES } from '../scanner/types.js';
 /**
  * Native MCP (Model Context Protocol) server for Nativ over stdio.
  *

package/dist/mcp/server.js

@@ -1,12 +1,15 @@
 import path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Writable } from 'node:stream';
 import { z } from 'zod';
-import { runTaskList, runTaskNext, runTaskStart, runTaskComplete, runTaskBlock, runTaskEscalate, runTaskAdd, runTaskProposePatch, } from '../commands/task.js';
-import { SUBAGENT_TYPES } from '../scanner/types.js';
+import { runTaskList, runTaskNext, runTaskStart, runTaskComplete, runTaskBlock, runTaskReclaim, runTaskEscalate, runTaskAdd, runTaskProposePatch, } from '../commands/task.js';
+import { SUBAGENT_TYPES, ESCALATION_TYPES } from '../scanner/types.js';
 import { runInit } from '../commands/init.js';
+import { runTriage } from '../commands/triage.js';
 import { runStatus } from '../commands/status.js';
 import { runDoctor } from '../commands/doctor.js';
+import { runValidate } from '../commands/validate.js';
 import { runWorktreeCreate, runWorktreeList, runWorktreeMerge, runWorktreeRemove, } from '../commands/worktree.js';
 import { runDbStatus, runDbInspect, runDbDiff } from '../commands/db.js';
 import { runVerify } from '../commands/verify.js';
@@ -19,13 +22,7 @@ import { captureOutput } from './capture.js';
 import { registerMcpResources } from './resources.js';
 export { captureOutput } from './capture.js';
 export { registerMcpResources, MCP_RESOURCES } from './resources.js';
-export const ESCALATION_TYPES = [
-    'contract_drift',
-    'schema_flaw',
-    'missing_credential',
-    'dependency_conflict',
-    'architectural_ambiguity',
-];
+export { ESCALATION_TYPES } from '../scanner/types.js';
 /**
  * Native MCP (Model Context Protocol) server for Nativ over stdio.
  *
@@ -46,14 +43,15 @@ export function createMcpServer(targetDirArg) {
         inputSchema: {},
     }, () => captureOutput(() => runTaskNext(targetDir, { json: true })));
     registerNativTool('task_list', {
-        description: 'List project tasks from .ai/master_plan.json with optional filters (JSON).',
+        description: 'List project tasks from .ai/master_plan.json with optional filters (JSON summary; full for every field).',
         inputSchema: {
             available: z.boolean().optional().describe('Only tasks that are unblocked and ready for execution'),
             status: z.enum(['pending', 'in_progress', 'completed', 'blocked']).optional().describe('Filter by task status'),
             milestone: z.string().optional().describe('Filter by milestone ID or name'),
             fastPath: z.boolean().optional().describe('Only fast-path tasks'),
+            full: z.boolean().optional().describe('Return every task field; the default is a short summary per task'),
         },
-    }, ({ available, status, milestone, fastPath }) => captureOutput(() => runTaskList(targetDir, { available, status, milestone, fastPath, json: true })));
+    }, ({ available, status, milestone, fastPath, full }) => captureOutput(() => runTaskList(targetDir, { available, status, milestone, fastPath, json: true, brief: !full })));
     registerNativTool('task_add', {
         description: 'Append a task to .ai/master_plan.json with an auto-incremented ID (JSON). Goes to the given milestone, else the active one; ' +
             'fastPath routes it to the fast-path milestone (created on first use).',
@@ -84,9 +82,12 @@ export function createMcpServer(targetDirArg) {
         json: true,
     })));
     registerNativTool('task_start', {
-        description: 'Mark a task as in_progress.',
-        inputSchema: { taskId: z.string().min(1).describe('Task ID, e.g. task-12') },
-    }, ({ taskId }) => captureOutput(() => runTaskStart(taskId, targetDir)));
+        description: 'Claim a task and mark it in_progress. Refused when it is blocked, completed, waits on unfinished dependencies, or another agent holds a fresh claim. Calling it again on your own task refreshes the claim.',
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+            agent: z.string().optional().describe('Your agent id, so parallel agents do not take the same task'),
+        },
+    }, ({ taskId, agent }) => captureOutput(() => runTaskStart(taskId, targetDir, { agent })));
     registerNativTool('task_complete', {
         description: "Mark a task as completed (always executes its verificationCommand; verification cannot be skipped over MCP). Advances the milestone when all its tasks are done.",
         inputSchema: {
@@ -115,6 +116,33 @@ export function createMcpServer(targetDirArg) {
             reason: z.string().min(1).describe('Why the task is blocked'),
         },
     }, ({ taskId, reason }) => captureOutput(() => runTaskBlock(taskId, reason, targetDir)));
+    registerNativTool('triage', {
+        description: 'Self-heal escalations: evaluate pending escalations (or one), apply sandbox-proven additive contract fixes and unblock their tasks. Returns compact JSON; items classified REQUIRE_HUMAN_DECISION carry a humanCard to present to the human.',
+        inputSchema: {
+            escalationId: z.string().optional().describe('Triage only this escalation, e.g. esc-03; default: every pending one'),
+            apply: z.boolean().optional().describe('Write proven safe patches and unblock tasks (default true)'),
+        },
+    }, ({ escalationId, apply }) => captureOutput(() => runTriage(escalationId, targetDir, {
+        all: !escalationId,
+        apply: apply ?? true,
+        json: true,
+        interactive: false,
+        // stdout carries the MCP protocol, so triage output is routed into the captured tool result.
+        output: new Writable({
+            write(chunk, _encoding, done) {
+                console.log(String(chunk).replace(/\n$/, ''));
+                done();
+            },
+        }),
+    })));
+    registerNativTool('task_reclaim', {
+        description: 'Put in_progress tasks whose agent stopped (claim older than olderThanHours, default 4) back to pending. Pass taskId to reclaim one task that has a stale or unrecorded claim.',
+        inputSchema: {
+            taskId: z.string().optional().describe('Reclaim only this task'),
+            olderThanHours: z.number().positive().optional().describe('Age at which a claim counts as abandoned'),
+            dryRun: z.boolean().optional().describe('Report without changing the plan'),
+        },
+    }, ({ taskId, olderThanHours, dryRun }) => captureOutput(() => runTaskReclaim(taskId, targetDir, { olderThan: olderThanHours, dryRun, json: true })));
     registerNativTool('task_escalate', {
         description: 'Escalate a contract or architectural blocker to the Architect (writes .ai/escalation.json and blocks the task).',
         inputSchema: {
@@ -192,6 +220,17 @@ export function createMcpServer(targetDirArg) {
         description: 'Summarize execution progress across all milestones and tasks.',
         inputSchema: {},
     }, () => captureOutput(() => runStatus(targetDir)));
+    registerNativTool('validate', {
+        description: 'Read-only integrity check of the .ai/ contracts, master plan, spec references and role guides. ' +
+            'Returns only problems (✖ errors, ⚠ warnings) and the verdict; an error result means a contract is missing or malformed.',
+        inputSchema: {},
+    }, async () => {
+        const result = await captureOutput(() => runValidate(targetDir));
+        const text = result.content[0]?.type === 'text' ? result.content[0].text : '';
+        const problems = text.split('\n').filter((line) => /[✖⚠]/.test(line) && !/validation failed with errors/i.test(line)).map((line) => line.trim());
+        const verdict = result.isError ? 'Validation failed.' : 'All contracts are valid.';
+        return { ...result, content: [{ type: 'text', text: [...problems, verdict].join('\n') }] };
+    });
     registerNativTool('doctor', {
         description: 'Read-only health check of the Claude Code integration: MCP server, hooks, permissions, agents, enforcement mode and provider availability (JSON). ' +
             'Reports drift but never repairs it; repairing is `nativ doctor --fix` in a terminal.',

package/dist/providers/claude-api.js

@@ -68,6 +68,9 @@ export function createClaudeApiProvider(deps = {}) {
                     throw new ProviderError('NO_CREDENTIALS', 'The Anthropic API key was rejected.');
                 if (/timeout|timed out/i.test(name + message))
                     throw new ProviderError('TIMEOUT', `Claude did not answer within ${timeout}ms.`);
+                if ((status !== undefined && status >= 500) || /APIConnectionError|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|socket hang up|fetch failed/i.test(name + message)) {
+                    throw new ProviderError('TRANSIENT', message.slice(0, 300));
+                }
                 throw new ProviderError('BAD_RESPONSE', message.slice(0, 300));
             }
         },

package/dist/providers/gemini.js

@@ -52,7 +52,8 @@ export function createGeminiProvider(deps = {}) {
                 const name = err?.name ?? '';
                 if (name === 'TimeoutError' || name === 'AbortError')
                     throw new ProviderError('TIMEOUT', `Gemini did not answer within ${timeout}ms.`);
-                throw new ProviderError('BAD_RESPONSE', err instanceof Error ? err.message : String(err));
+                // fetch only throws here when the request never got an answer: DNS, refused or reset connection.
+                throw new ProviderError('TRANSIENT', err instanceof Error ? err.message : String(err));
             }
             if (res.status === 429) {
                 const seconds = Number(res.headers.get('retry-after'));
@@ -60,6 +61,8 @@ export function createGeminiProvider(deps = {}) {
             }
             if (res.status === 401 || res.status === 403)
                 throw new ProviderError('NO_CREDENTIALS', 'The Gemini API key was rejected.');
+            if (res.status >= 500)
+                throw new ProviderError('TRANSIENT', `Gemini responded with HTTP ${res.status}.`);
             if (!res.ok)
                 throw new ProviderError('BAD_RESPONSE', `Gemini responded with HTTP ${res.status}.`);
             let body;

package/dist/providers/registry.d.ts

@@ -31,8 +31,12 @@ export declare function providerCooldownRemaining(root: string, id: ProviderId,
 export declare function resolveProviderChain(role: ProviderRole, root: string, options?: RegistryOptions): Provider[];
 export declare function resolveProvider(role: ProviderRole, root: string, options?: RegistryOptions): Provider | null;
 /**
- * Runs the request against each provider in turn. A rate limit puts that provider on cooldown, and any
- * ProviderError falls through to the next one. Throws NO_CREDENTIALS when nothing is available and the
+ * Runs the request against each provider in turn. A TRANSIENT failure (network, 5xx) is retried on the same
+ * provider up to MAX_TRANSIENT_RETRIES times with jittered backoff. A rate limit puts that provider on cooldown, and
+ * any other ProviderError falls through to the next one. Throws NO_CREDENTIALS when nothing is available and the
  * last error when every provider failed, so the caller can drop to its deterministic path.
  */
+export declare const MAX_TRANSIENT_RETRIES = 2;
+/** 0.5s, then 1s, each plus up to 50% jitter so parallel agents do not retry in lockstep. */
+export declare function transientBackoffMs(attempt: number, random?: () => number): number;
 export declare function completeWithChain(role: ProviderRole, root: string, request: CompleteRequest, options?: RegistryOptions): Promise<ChainResult>;

package/dist/providers/registry.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { writeJsonAtomicSync } from '../core/lock-manager.js';
 import { createClaudeApiProvider } from './claude-api.js';
 import { createClaudeCliProvider, DEFAULT_LIMIT_COOLDOWN_MS } from './claude-cli.js';
 import { createGeminiProvider } from './gemini.js';
@@ -42,11 +43,7 @@ function readCooldowns(root) {
 }
 function writeCooldowns(root, cooldownUntil) {
     try {
-        const file = path.join(root, STATE_FILE);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        const tmp = `${file}.${process.pid}.tmp`;
-        fs.writeFileSync(tmp, JSON.stringify({ cooldownUntil }, null, 2), 'utf8');
-        fs.renameSync(tmp, file);
+        writeJsonAtomicSync(path.join(root, STATE_FILE), { cooldownUntil });
     }
     catch {
         // Cooldown is an optimisation; failing to persist it must never fail the call.
@@ -93,10 +90,17 @@ export function resolveProvider(role, root, options = {}) {
     return resolveProviderChain(role, root, options)[0] ?? null;
 }
 /**
- * Runs the request against each provider in turn. A rate limit puts that provider on cooldown, and any
- * ProviderError falls through to the next one. Throws NO_CREDENTIALS when nothing is available and the
+ * Runs the request against each provider in turn. A TRANSIENT failure (network, 5xx) is retried on the same
+ * provider up to MAX_TRANSIENT_RETRIES times with jittered backoff. A rate limit puts that provider on cooldown, and
+ * any other ProviderError falls through to the next one. Throws NO_CREDENTIALS when nothing is available and the
  * last error when every provider failed, so the caller can drop to its deterministic path.
  */
+export const MAX_TRANSIENT_RETRIES = 2;
+/** 0.5s, then 1s, each plus up to 50% jitter so parallel agents do not retry in lockstep. */
+export function transientBackoffMs(attempt, random = Math.random) {
+    const base = 500 * 2 ** attempt;
+    return Math.round(base + base * 0.5 * random());
+}
 export async function completeWithChain(role, root, request, options = {}) {
     const chain = resolveProviderChain(role, root, options);
     if (!chain.length)
@@ -104,17 +108,25 @@ export async function completeWithChain(role, root, request, options = {}) {
     const models = (options.config ?? loadProviderConfig(root)).models ?? {};
     const now = options.deps?.now ?? Date.now;
     let lastError = null;
+    const sleep = options.deps?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     for (const provider of chain) {
         const model = request.model ?? models[provider.id] ?? provider.defaultModel;
-        try {
-            const text = await provider.complete({ ...request, model }, root);
-            return { provider: provider.id, model, text };
-        }
-        catch (err) {
-            const failure = err instanceof ProviderError ? err : new ProviderError('BAD_RESPONSE', err instanceof Error ? err.message : String(err));
-            if (failure.code === 'RATE_LIMITED')
-                setProviderCooldown(root, provider.id, failure.retryAfterMs ?? DEFAULT_LIMIT_COOLDOWN_MS, now());
-            lastError = failure;
+        for (let attempt = 0;; attempt++) {
+            try {
+                const text = await provider.complete({ ...request, model }, root);
+                return { provider: provider.id, model, text };
+            }
+            catch (err) {
+                const failure = err instanceof ProviderError ? err : new ProviderError('BAD_RESPONSE', err instanceof Error ? err.message : String(err));
+                lastError = failure;
+                if (failure.code === 'TRANSIENT' && attempt < MAX_TRANSIENT_RETRIES) {
+                    await sleep(transientBackoffMs(attempt));
+                    continue;
+                }
+                if (failure.code === 'RATE_LIMITED')
+                    setProviderCooldown(root, provider.id, failure.retryAfterMs ?? DEFAULT_LIMIT_COOLDOWN_MS, now());
+                break;
+            }
         }
     }
     throw lastError ?? new ProviderError('BAD_RESPONSE', 'Every provider failed.');