@njeybe/nativ 2.5.0 → 2.6.0

package/dist/core/session-memory.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function getSessionMemoryDir(targetDir) {
+    return path.join(targetDir, '.ai', 'memory', 'sessions');
+}
+export function getSessionIndexPath(targetDir) {
+    return path.join(getSessionMemoryDir(targetDir), 'index.json');
+}
+export function getLatestSessionPath(targetDir) {
+    return path.join(getSessionMemoryDir(targetDir), 'latest.json');
+}
+export function loadSessionIndex(targetDir) {
+    const indexPath = getSessionIndexPath(targetDir);
+    if (!fs.existsSync(indexPath)) {
+        return {
+            version: '1.0.0',
+            updatedAt: new Date().toISOString(),
+            sessions: [],
+        };
+    }
+    try {
+        const raw = fs.readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.sessions)) {
+            return {
+                version: '1.0.0',
+                updatedAt: new Date().toISOString(),
+                sessions: [],
+            };
+        }
+        return parsed;
+    }
+    catch {
+        return {
+            version: '1.0.0',
+            updatedAt: new Date().toISOString(),
+            sessions: [],
+        };
+    }
+}
+export function saveSessionIndex(targetDir, index) {
+    const dir = getSessionMemoryDir(targetDir);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    index.updatedAt = new Date().toISOString();
+    fs.writeFileSync(getSessionIndexPath(targetDir), JSON.stringify(index, null, 2), 'utf8');
+}
+export function saveSessionCheckpoint(targetDir, input) {
+    const dir = getSessionMemoryDir(targetDir);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const now = new Date();
+    const dateStr = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    const sessionId = input.sessionId || `sess-${dateStr}`;
+    const checkpoint = {
+        sessionId,
+        timestamp: now.toISOString(),
+        ...(input.role ? { role: input.role.trim() } : {}),
+        ...(input.taskId ? { taskId: input.taskId.trim() } : {}),
+        summary: input.summary.trim(),
+        ...(input.decisions && input.decisions.length > 0 ? { decisions: input.decisions.map((d) => d.trim()) } : {}),
+        ...(input.obstacles && input.obstacles.length > 0 ? { obstacles: input.obstacles.map((o) => o.trim()) } : {}),
+        ...(input.nextSteps && input.nextSteps.length > 0 ? { nextSteps: input.nextSteps.map((n) => n.trim()) } : {}),
+        ...(input.activeFiles && input.activeFiles.length > 0 ? { activeFiles: input.activeFiles.map((f) => f.trim()) } : {}),
+    };
+    // Write individual session file
+    const sessionPath = path.join(dir, `${sessionId}.json`);
+    fs.writeFileSync(sessionPath, JSON.stringify(checkpoint, null, 2), 'utf8');
+    // Write latest.json
+    fs.writeFileSync(getLatestSessionPath(targetDir), JSON.stringify(checkpoint, null, 2), 'utf8');
+    // Update index
+    const index = loadSessionIndex(targetDir);
+    index.latestSessionId = sessionId;
+    // Remove existing entry with same sessionId if updating
+    index.sessions = index.sessions.filter((s) => s.sessionId !== sessionId);
+    index.sessions.unshift({
+        sessionId,
+        timestamp: checkpoint.timestamp,
+        role: checkpoint.role,
+        taskId: checkpoint.taskId,
+        summary: checkpoint.summary,
+    });
+    // Keep index trimmed to 50 most recent sessions
+    if (index.sessions.length > 50) {
+        index.sessions = index.sessions.slice(0, 50);
+    }
+    saveSessionIndex(targetDir, index);
+    return checkpoint;
+}
+export function getLatestSession(targetDir) {
+    const latestPath = getLatestSessionPath(targetDir);
+    if (!fs.existsSync(latestPath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(latestPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function getSession(targetDir, sessionId) {
+    const sessionPath = path.join(getSessionMemoryDir(targetDir), `${sessionId}.json`);
+    if (!fs.existsSync(sessionPath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(sessionPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function listSessions(targetDir, limit = 10) {
+    const index = loadSessionIndex(targetDir);
+    return index.sessions.slice(0, limit);
+}

package/dist/core/setup/pm-playbook.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The project manager's playbook. The SessionStart hook prints it into the main session only:
+ * subagents load CLAUDE.md and AGENTS.md on every turn, so anything kept there is paid for by every worker.
+ */
+export declare const PM_PLAYBOOK = "## Working as Project Manager\n\n- Start each session with `nativ task next --json` (or the `nativ_task_next` MCP tool).\n- Delegate, do not implement. Hand each task to the `worker` agent by task id, passing the task's `recommendedModel` (haiku, sonnet or opus) as the Agent tool's `model`; with none, the worker's default applies. Ask the `verifier` agent for an independent check before you mark a milestone done. Ask the `architect` agent for anything that changes a contract.\n- Before the architect designs on existing code, run the `explorer` when `.ai/codebase_map.md` is missing or its commit is well behind `HEAD`, and pass its report to the architect. Give the explorer the current commit (`git rev-parse --short HEAD`); it cannot look it up. Pass `model: haiku` for a single lookup such as \"where is the auth middleware?\".\n- Keep usage low. Run this session on Sonnet. Agent defaults: architect Opus, worker Sonnet, verifier Haiku. Pass `haiku` for mechanical tasks (wording, docs, renames) and `sonnet` for the verifier at the end of a milestone. Never pass a model the human did not choose.\n- Independent tasks can run in parallel in worktrees (`nativ worktree create <taskId>`). On a Claude subscription every agent draws from the same usage limit, so run two or three at a time, not ten.\n- You may not edit `.ai/`. If the enforcement hook warns about a file, that is a scope or contract gap: escalate with `nativ task escalate`, do not edit around it.\n- `nativ doctor` confirms the integration is intact. Run it after updating Claude Code or nativ, and whenever hooks or MCP tools seem to be missing.\n\n## Autonomous execution\n\nWhen told to run autonomously (\"run the queue\", \"execute milestone\", AFK mode):\n1. `nativ_task_next`, then `nativ_task_start`.\n2. Delegate to the `worker` agent with the task id and recommended model.\n3. The worker completes the task itself; `nativ task complete` already ran the check. Do not run `nativ_verify` or `nativ_task_complete` again for it.\n4. Loop to the next task immediately, without asking the human.\n5. Stop only when the milestone is done (ask the `verifier` for a milestone check, then tell the human) or when a task is blocked or escalated (present the four-part summary).\n\n## Talking to the human\n\nThe human is the product owner, not a log reader. For a blocker, trade-off or escalation use four parts in plain words: what the user would see; why it happens, as simple cause and effect; what is affected and what is safe; two or three options with the best marked `(Recommended)`, then one direct question. Say \"the app tried to link a record to an item that does not exist yet\", not \"foreign key constraint violation\". Never paste stack traces; put raw output in a collapsed `<details>` block.";

package/dist/core/setup/pm-playbook.js

@@ -0,0 +1,26 @@
+/**
+ * The project manager's playbook. The SessionStart hook prints it into the main session only:
+ * subagents load CLAUDE.md and AGENTS.md on every turn, so anything kept there is paid for by every worker.
+ */
+export const PM_PLAYBOOK = `## Working as Project Manager
+
+- Start each session with \`nativ task next --json\` (or the \`nativ_task_next\` MCP tool).
+- Delegate, do not implement. Hand each task to the \`worker\` agent by task id, passing the task's \`recommendedModel\` (haiku, sonnet or opus) as the Agent tool's \`model\`; with none, the worker's default applies. Ask the \`verifier\` agent for an independent check before you mark a milestone done. Ask the \`architect\` agent for anything that changes a contract.
+- Before the architect designs on existing code, run the \`explorer\` when \`.ai/codebase_map.md\` is missing or its commit is well behind \`HEAD\`, and pass its report to the architect. Give the explorer the current commit (\`git rev-parse --short HEAD\`); it cannot look it up. Pass \`model: haiku\` for a single lookup such as "where is the auth middleware?".
+- Keep usage low. Run this session on Sonnet. Agent defaults: architect Opus, worker Sonnet, verifier Haiku. Pass \`haiku\` for mechanical tasks (wording, docs, renames) and \`sonnet\` for the verifier at the end of a milestone. Never pass a model the human did not choose.
+- Independent tasks can run in parallel in worktrees (\`nativ worktree create <taskId>\`). On a Claude subscription every agent draws from the same usage limit, so run two or three at a time, not ten.
+- You may not edit \`.ai/\`. If the enforcement hook warns about a file, that is a scope or contract gap: escalate with \`nativ task escalate\`, do not edit around it.
+- \`nativ doctor\` confirms the integration is intact. Run it after updating Claude Code or nativ, and whenever hooks or MCP tools seem to be missing.
+
+## Autonomous execution
+
+When told to run autonomously ("run the queue", "execute milestone", AFK mode):
+1. \`nativ_task_next\`, then \`nativ_task_start\`.
+2. Delegate to the \`worker\` agent with the task id and recommended model.
+3. The worker completes the task itself; \`nativ task complete\` already ran the check. Do not run \`nativ_verify\` or \`nativ_task_complete\` again for it.
+4. Loop to the next task immediately, without asking the human.
+5. Stop only when the milestone is done (ask the \`verifier\` for a milestone check, then tell the human) or when a task is blocked or escalated (present the four-part summary).
+
+## Talking to the human
+
+The human is the product owner, not a log reader. For a blocker, trade-off or escalation use four parts in plain words: what the user would see; why it happens, as simple cause and effect; what is affected and what is safe; two or three options with the best marked \`(Recommended)\`, then one direct question. Say "the app tried to link a record to an item that does not exist yet", not "foreign key constraint violation". Never paste stack traces; put raw output in a collapsed \`<details>\` block.`;

package/dist/core/setup/session-context.js

@@ -2,6 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { ROLE_ENV, loadEnforcementMode, parseJsonLoose } from '../enforcement.js';
 import { resolveProjectRoot } from '../root-resolver.js';
+import { loadEscalationFile } from '../../governor/store.js';
+import { DEFAULT_STALE_HOURS, claimAgeHours, isStaleClaim } from '../task-claims.js';
+import { PM_PLAYBOOK } from './pm-playbook.js';
 function readPlanTasks(root) {
     try {
         const plan = parseJsonLoose(fs.readFileSync(path.join(root, '.ai', 'master_plan.json'), 'utf8'));
@@ -15,6 +18,7 @@ function readPlanTasks(root) {
                         status: typeof t.status === 'string' ? t.status : 'pending',
                         dependencies: Array.isArray(t.dependencies) ? t.dependencies : [],
                         targetFiles: Array.isArray(t.targetFiles) ? t.targetFiles : [],
+                        ...(typeof t.claimedAt === 'string' ? { claimedAt: t.claimedAt } : {}),
                     });
                 }
             }
@@ -25,6 +29,30 @@ function readPlanTasks(root) {
         return [];
     }
 }
+/** Pending escalations and blocked tasks, so a fresh session resumes where the last one stopped. */
+function openItems(root, tasks) {
+    let pending = 0;
+    try {
+        pending = loadEscalationFile(root, path.basename(root)).escalations.filter((e) => e?.status === 'pending_review').length;
+    }
+    catch {
+        // An unreadable escalation file must not hide the rest of the orientation.
+    }
+    const blocked = tasks.filter((t) => t.status === 'blocked').map((t) => t.id);
+    const stale = tasks.filter((t) => isStaleClaim(t, DEFAULT_STALE_HOURS));
+    if (!pending && !blocked.length && !stale.length)
+        return null;
+    const parts = [];
+    if (blocked.length)
+        parts.push(`blocked: ${blocked.slice(0, 5).join(', ')}${blocked.length > 5 ? ` +${blocked.length - 5}` : ''}`);
+    if (stale.length) {
+        const list = stale.slice(0, 5).map((t) => `${t.id} (${Math.floor(claimAgeHours(t) ?? 0)}h)`).join(', ');
+        parts.push(`stale in_progress: ${list}: run \`nativ task reclaim\``);
+    }
+    if (pending)
+        parts.push(`${pending} escalation(s) pending: run \`nativ_triage\` (or \`nativ triage --all --apply --json\`)`);
+    return `Open: ${parts.join('; ')}.`;
+}
 /** 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);
@@ -36,8 +64,8 @@ export function buildSessionContext(cwd, env = process.env) {
     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.`,
+        'nativ project (role-based workflow).',
+        `Session role: ${role}. Enforcement: ${loadEnforcementMode(root)}. Writes outside the task's targetFiles are flagged; .ai/ is architect-only.`,
     ];
     if (active.length) {
         for (const t of active)
@@ -49,7 +77,12 @@ export function buildSessionContext(cwd, env = process.env) {
     else {
         lines.push('No task is in progress or ready.');
     }
+    const open = openItems(root, tasks);
+    if (open)
+        lines.push(open);
     lines.push('Prefer the nativ_* MCP tools (or the `nativ` CLI). Do not edit .ai/ directly: escalate contract gaps with `nativ task escalate`.');
+    if (role === 'project manager')
+        lines.push('', PM_PLAYBOOK);
     return lines.join('\n');
 }
 /** `nativ hook context`: prints the SessionStart hook output. Never throws and always prints valid JSON or nothing. */

package/dist/core/setup/setup-planner.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { MCP_SERVER_NAME, AGENT_FILES, resolveCliInvocation, stampManaged, managedState, } from './types.js';
+import { MCP_SERVER_NAME, AGENT_FILES, resolveCliInvocation, isMachineBoundPath, stampManaged, managedState, } from './types.js';
 import { buildDesiredConfig, mergeClaudeSettings, mergeMcpConfig, isObject, } from './config-merger.js';
 import { loadEnforcementMode, parseJsonLoose } from '../enforcement.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -38,7 +38,7 @@ export function configuredInvocation(root) {
         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)) };
+        return { command: server.command, prefixArgs, portable: ![server.command, ...prefixArgs].some(isMachineBoundPath) };
     }
     catch {
         return null;

package/dist/core/setup/types.d.ts

@@ -6,6 +6,8 @@ export declare const MANAGED_PATTERN: RegExp;
 export declare const PRE_TOOL_USE_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
 export declare const SESSION_START_MATCHER = "startup|resume|clear|compact";
 export declare const HOOK_TIMEOUT_SECONDS = 10;
+/** `.mcp.json` is shared between machines, so a path absolute on either OS ties it to one machine. */
+export declare function isMachineBoundPath(p: string): boolean;
 export type AssetAction = 'created' | 'updated' | 'unchanged' | 'skipped';
 export interface AssetChange {
     /** Path relative to the project root, forward slashes. */

package/dist/core/setup/types.js

@@ -10,6 +10,10 @@ export const MANAGED_PATTERN = /\n?<!-- nativ:managed sha256=([0-9a-f]{12}) -->\
 export const PRE_TOOL_USE_MATCHER = 'Write|Edit|MultiEdit|NotebookEdit';
 export const SESSION_START_MATCHER = 'startup|resume|clear|compact';
 export const HOOK_TIMEOUT_SECONDS = 10;
+/** `.mcp.json` is shared between machines, so a path absolute on either OS ties it to one machine. */
+export function isMachineBoundPath(p) {
+    return path.posix.isAbsolute(p) || path.win32.isAbsolute(p);
+}
 export function defaultHasBinary(name) {
     try {
         return spawnSync(process.platform === 'win32' ? 'where' : 'which', [name], { stdio: 'ignore' }).status === 0;
@@ -25,7 +29,7 @@ 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)) };
+        return { command, prefixArgs, portable: ![command, ...prefixArgs].some(isMachineBoundPath) };
     }
     if ((options.hasBinary ?? defaultHasBinary)('nativ'))
         return { command: 'nativ', prefixArgs: [], portable: true };

package/dist/core/task-claims.d.ts

@@ -0,0 +1,15 @@
+import type { MasterPlan, MasterPlanTask } from '../scanner/types.js';
+/** A claim with no fresh `task start` for this long is presumed abandoned (crashed or closed agent). */
+export declare const DEFAULT_STALE_HOURS = 4;
+export declare const AGENT_ID_ENV = "NATIV_AGENT_ID";
+export declare function resolveAgentId(explicit?: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** Hours since the task was claimed, or null when the claim time is unknown (claimed before claims were recorded). */
+export declare function claimAgeHours(task: {
+    claimedAt?: string;
+}, now?: number): number | null;
+export declare function isStaleClaim(task: {
+    status: string;
+    claimedAt?: string;
+}, hours?: number, now?: number): boolean;
+/** Why `task start` must not claim this task, or null when it may. */
+export declare function startRefusal(plan: MasterPlan, task: MasterPlanTask, agent: string | undefined, now?: number): string | null;

package/dist/core/task-claims.js

@@ -0,0 +1,32 @@
+/** A claim with no fresh `task start` for this long is presumed abandoned (crashed or closed agent). */
+export const DEFAULT_STALE_HOURS = 4;
+export const AGENT_ID_ENV = 'NATIV_AGENT_ID';
+export function resolveAgentId(explicit, env = process.env) {
+    return (explicit ?? env[AGENT_ID_ENV] ?? '').trim() || undefined;
+}
+/** Hours since the task was claimed, or null when the claim time is unknown (claimed before claims were recorded). */
+export function claimAgeHours(task, now = Date.now()) {
+    const at = task.claimedAt ? Date.parse(task.claimedAt) : NaN;
+    return Number.isFinite(at) ? Math.max(0, (now - at) / 3_600_000) : null;
+}
+export function isStaleClaim(task, hours = DEFAULT_STALE_HOURS, now = Date.now()) {
+    const age = claimAgeHours(task, now);
+    return task.status === 'in_progress' && age !== null && age >= hours;
+}
+/** Why `task start` must not claim this task, or null when it may. */
+export function startRefusal(plan, task, agent, now = Date.now()) {
+    if (task.status === 'completed')
+        return `Task [${task.id}] is already completed.`;
+    if (task.status === 'blocked') {
+        const why = task.notes ? ` (${task.notes})` : '';
+        return `Task [${task.id}] is blocked${why}. Resolve it with \`nativ triage\` first; a human can override with \`nativ task start ${task.id} --force\`.`;
+    }
+    const done = new Set(plan.milestones.flatMap((m) => m.tasks).filter((t) => t.status === 'completed').map((t) => t.id));
+    const waiting = (task.dependencies ?? []).filter((d) => !done.has(d));
+    if (waiting.length)
+        return `Task [${task.id}] waits on unfinished dependencies: ${waiting.join(', ')}.`;
+    if (task.status === 'in_progress' && task.claimedBy && agent && task.claimedBy !== agent && !isStaleClaim(task, DEFAULT_STALE_HOURS, now)) {
+        return `Task [${task.id}] is already claimed by ${task.claimedBy} since ${task.claimedAt}. Pick another task with \`nativ task next\`.`;
+    }
+    return null;
+}

package/dist/core/tier1-liaison.d.ts

@@ -109,6 +109,7 @@ export declare function hasGeminiApiKey(root?: string): boolean;
  */
 export declare function redactSecrets(text: string, extraSecrets?: string[]): string;
 export declare function loadTriageConfig(root: string): Partial<TriageConfig>;
+/** Merges triage settings into `.nativ/config.json` under its lock. Throws when the file cannot be written. */
 export declare function saveTriageConfig(root: string, update: Partial<TriageConfig>): void;
 /**
  * Tier 1 AI Strategist Liaison instance managing escalation evaluation,

package/dist/core/tier1-liaison.js

@@ -15,6 +15,8 @@ import path from 'node:path';
 import { MASK } from '../db/env-parser.js';
 import { escalationPath, loadEscalationFile } from '../governor/store.js';
 import { applySelfHealingProposal } from '../governor/index.js';
+import { notifyHuman } from './notify.js';
+import { mutateJsonFileSync } from './lock-manager.js';
 import { CLAUDE_CLI_DEFAULT_MODEL, completeWithChain, resolveAnthropicApiKey, resolveGeminiApiKey as resolveGeminiKey, resolveProviderChain, } from '../providers/index.js';
 /** Triage runs often and in the background, so it defaults to the cheapest Claude tier. */
 export const DEFAULT_MODEL = CLAUDE_CLI_DEFAULT_MODEL;
@@ -115,36 +117,18 @@ export function loadTriageConfig(root) {
     }
     return {};
 }
+/** Merges triage settings into `.nativ/config.json` under its lock. Throws when the file cannot be written. */
 export function saveTriageConfig(root, update) {
-    const nativDir = path.join(root, '.nativ');
-    const configFile = path.join(nativDir, 'config.json');
-    try {
-        if (!fs.existsSync(nativDir))
-            fs.mkdirSync(nativDir, { recursive: true });
-        let existing = {};
-        if (fs.existsSync(configFile)) {
-            try {
-                existing = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-            }
-            catch {
-                existing = {};
-            }
-        }
-        const currentTriage = (existing.triage && typeof existing.triage === 'object') ? existing.triage : {};
+    mutateJsonFileSync(path.join(root, '.nativ', 'config.json'), (config) => {
+        const triage = config.triage && typeof config.triage === 'object' ? config.triage : {};
         if (typeof update.autoTriageEnabled === 'boolean')
-            currentTriage.autoTriageEnabled = update.autoTriageEnabled;
+            triage.autoTriageEnabled = update.autoTriageEnabled;
         if (update.riskThreshold)
-            currentTriage.riskThreshold = update.riskThreshold;
+            triage.riskThreshold = update.riskThreshold;
         if (update.model)
-            currentTriage.model = update.model;
-        existing.triage = currentTriage;
-        const tmp = `${configFile}.${process.pid}.${Date.now()}.tmp`;
-        fs.writeFileSync(tmp, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-        fs.renameSync(tmp, configFile);
-    }
-    catch {
-        // Ignore write failures gracefully
-    }
+            triage.model = update.model;
+        config.triage = triage;
+    });
 }
 /**
  * Tier 1 AI Strategist Liaison instance managing escalation evaluation,
@@ -215,7 +199,12 @@ export class Tier1Liaison {
         if (typeof body.model === 'string' && body.model.trim()) {
             this.config.model = body.model.trim();
         }
-        saveTriageConfig(this.root, this.config);
+        try {
+            saveTriageConfig(this.root, this.config);
+        }
+        catch (err) {
+            return { ok: false, error: `Could not save .nativ/config.json: ${err instanceof Error ? err.message : String(err)}` };
+        }
         return { ok: true, config: { ...this.config } };
     }
     async evaluate(escalationId) {
@@ -349,6 +338,15 @@ Respond with strictly valid JSON:
             this.stats.autoResolved++;
         else if (classification === 'REQUIRE_HUMAN_DECISION')
             this.stats.escalatedToHuman++;
+        if (classification === 'REQUIRE_HUMAN_DECISION' && !autoPatchApplied) {
+            await notifyHuman(this.root, {
+                event: 'human_decision',
+                taskId,
+                escalationId,
+                summary: record.summary || 'A decision is needed',
+                ...(humanCard ? { question: humanCard.symptom, options: humanCard.options.map((o) => o.label) } : {}),
+            }).catch(() => { });
+        }
         const latencyMs = Date.now() - startTime;
         return {
             ok: true,

package/dist/core/verifier/output-digest.d.ts

@@ -0,0 +1,19 @@
+import type { VerificationResult } from './types.js';
+/** Lines of each output stream an agent sees for a failed check; the rest goes to the log file. */
+export declare const DIGEST_MAX_LINES = 40;
+/**
+ * Picks at most `maxLines` lines from a long test run, in their original order.
+ * Only called when `lines.length > maxLines`.
+ */
+export declare function digestLines(lines: string[], maxLines: number): string[];
+/** Short enough to keep in an agent's context; says how much was left out. */
+export declare function digestOutput(text: string, maxLines?: number): string;
+/** Writes the whole run to .nativ/logs/ and returns its project-relative path, or null if it cannot. */
+export declare function saveFullLog(root: string, taskId: string, result: VerificationResult): string | null;
+export interface FailureDigest {
+    stderr: string;
+    stdout: string;
+    logFile: string | null;
+}
+/** What a failed check shows an agent: a digest of each non-empty stream and where the full log is. */
+export declare function digestFailure(root: string, taskId: string, result: VerificationResult): FailureDigest;

package/dist/core/verifier/output-digest.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Lines of each output stream an agent sees for a failed check; the rest goes to the log file. */
+export const DIGEST_MAX_LINES = 40;
+/**
+ * Picks at most `maxLines` lines from a long test run, in their original order.
+ * Only called when `lines.length > maxLines`.
+ */
+export function digestLines(lines, maxLines) {
+    // TODO(human): choose which lines an agent needs to fix the failure.
+    return lines.slice(-maxLines);
+}
+/** Short enough to keep in an agent's context; says how much was left out. */
+export function digestOutput(text, maxLines = DIGEST_MAX_LINES) {
+    const lines = text.trim().split(/\r?\n/);
+    if (lines.length <= maxLines)
+        return lines.join('\n');
+    const kept = digestLines(lines, maxLines).slice(0, maxLines);
+    return `${kept.join('\n')}\n[... ${lines.length - kept.length} of ${lines.length} lines left out ...]`;
+}
+/** Writes the whole run to .nativ/logs/ and returns its project-relative path, or null if it cannot. */
+export function saveFullLog(root, taskId, result) {
+    try {
+        const dir = path.join(root, '.nativ', 'logs');
+        fs.mkdirSync(dir, { recursive: true });
+        // Logs can quote test data; keep them out of commits whatever the project's own ignore rules say.
+        const ignore = path.join(dir, '.gitignore');
+        if (!fs.existsSync(ignore))
+            fs.writeFileSync(ignore, '*\n');
+        const file = path.join(dir, `verify-${taskId.replace(/[^\w.-]/g, '_')}.log`);
+        const body = [`$ ${result.command}`, '--- stdout ---', result.stdout, '--- stderr ---', result.stderr];
+        if (result.error)
+            body.push('--- error ---', result.error);
+        fs.writeFileSync(file, body.join('\n'));
+        return path.relative(root, file).split(path.sep).join('/');
+    }
+    catch {
+        return null;
+    }
+}
+/** What a failed check shows an agent: a digest of each non-empty stream and where the full log is. */
+export function digestFailure(root, taskId, result) {
+    return {
+        stderr: result.stderr?.trim() ? digestOutput(result.stderr) : '',
+        stdout: result.stdout?.trim() ? digestOutput(result.stdout) : '',
+        logFile: saveFullLog(root, taskId, result),
+    };
+}

package/dist/db/data-engine.js

@@ -1,4 +1,5 @@
 import { detectEngine, maskConnectionString, MASK, parseFirestoreUrl, sqlitePathFromUrl } from './env-parser.js';
+import { loadSqlite } from './sqlite.js';
 /** Validates entity and identifier names to guard against SQL injection in DDL/identifiers. */
 function assertValidIdentifier(name, label = 'Identifier') {
     if (!name || typeof name !== 'string' || !/^[a-zA-Z0-9_.-]+$/.test(name.trim())) {
@@ -83,16 +84,16 @@ async function postgresFetch(url, entity, options) {
     await client.connect();
     try {
         // 1. Detect primary key
-        const pkRes = await client.query(`SELECT 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' AND tc.table_name = $1
+        const pkRes = await client.query(`SELECT 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' AND tc.table_name = $1
        LIMIT 1`, [entity]);
         const primaryKey = pkRes.rows[0]?.column_name ?? 'id';
         // 2. Detect searchable text columns
-        const colRes = await client.query(`SELECT column_name, data_type
-       FROM information_schema.columns
+        const colRes = await client.query(`SELECT column_name, data_type
+       FROM information_schema.columns
        WHERE table_schema = current_schema() AND table_name = $1`, [entity]);
         const allCols = colRes.rows.map((r) => r.column_name);
         // 3. Build search clause
@@ -171,11 +172,11 @@ async function postgresUpdate(url, entity, primaryKey, updates) {
     const client = new pg.Client({ connectionString: url, connectionTimeoutMillis: 8000, statement_timeout: 15000 });
     await client.connect();
     try {
-        const pkRes = await client.query(`SELECT 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' AND tc.table_name = $1
+        const pkRes = await client.query(`SELECT 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' AND tc.table_name = $1
        LIMIT 1`, [entity]);
         const pkCol = pkRes.rows[0]?.column_name ?? 'id';
         const keys = Object.keys(updates).filter((k) => k !== pkCol);
@@ -204,11 +205,11 @@ async function postgresDelete(url, entity, primaryKey) {
     const client = new pg.Client({ connectionString: url, connectionTimeoutMillis: 8000, statement_timeout: 15000 });
     await client.connect();
     try {
-        const pkRes = await client.query(`SELECT 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' AND tc.table_name = $1
+        const pkRes = await client.query(`SELECT 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' AND tc.table_name = $1
        LIMIT 1`, [entity]);
         const pkCol = pkRes.rows[0]?.column_name ?? 'id';
         const query = `DELETE FROM "${entity.replace(/"/g, '""')}" WHERE "${pkCol.replace(/"/g, '""')}" = $1`;
@@ -230,15 +231,15 @@ async function mysqlFetch(url, entity, options) {
     try {
         // 1. Detect primary key
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const [pkRows] = (await conn.query(`SELECT COLUMN_NAME
-       FROM information_schema.KEY_COLUMN_USAGE
-       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND CONSTRAINT_NAME = 'PRIMARY'
+        const [pkRows] = (await conn.query(`SELECT COLUMN_NAME
+       FROM information_schema.KEY_COLUMN_USAGE
+       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND CONSTRAINT_NAME = 'PRIMARY'
        LIMIT 1`, [entity]));
         const primaryKey = pkRows[0]?.COLUMN_NAME ?? 'id';
         // 2. Detect column names
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const [colRows] = (await conn.query(`SELECT COLUMN_NAME
-       FROM information_schema.COLUMNS
+        const [colRows] = (await conn.query(`SELECT COLUMN_NAME
+       FROM information_schema.COLUMNS
        WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`, [entity]));
         const allCols = colRows.map((r) => r.COLUMN_NAME);
         // 3. Search clause
@@ -309,9 +310,9 @@ async function mysqlUpdate(url, entity, primaryKey, updates) {
     const conn = await mysql.createConnection({ uri: url, connectTimeout: 8000 });
     try {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const [pkRows] = (await conn.query(`SELECT COLUMN_NAME
-       FROM information_schema.KEY_COLUMN_USAGE
-       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND CONSTRAINT_NAME = 'PRIMARY'
+        const [pkRows] = (await conn.query(`SELECT COLUMN_NAME
+       FROM information_schema.KEY_COLUMN_USAGE
+       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND CONSTRAINT_NAME = 'PRIMARY'
        LIMIT 1`, [entity]));
         const pkCol = pkRows[0]?.COLUMN_NAME ?? 'id';
         const keys = Object.keys(updates).filter((k) => k !== pkCol);
@@ -340,9 +341,9 @@ async function mysqlDelete(url, entity, primaryKey) {
     const conn = await mysql.createConnection({ uri: url, connectTimeout: 8000 });
     try {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const [pkRows] = (await conn.query(`SELECT COLUMN_NAME
-       FROM information_schema.KEY_COLUMN_USAGE
-       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND CONSTRAINT_NAME = 'PRIMARY'
+        const [pkRows] = (await conn.query(`SELECT COLUMN_NAME
+       FROM information_schema.KEY_COLUMN_USAGE
+       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND CONSTRAINT_NAME = 'PRIMARY'
        LIMIT 1`, [entity]));
         const pkCol = pkRows[0]?.COLUMN_NAME ?? 'id';
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -359,7 +360,7 @@ async function mysqlDelete(url, entity, primaryKey) {
 // ─── SQLite Driver (node:sqlite) ──────────────────────────────────────────────
 async function sqliteFetch(url, entity, options) {
     assertValidIdentifier(entity, 'table name');
-    const { DatabaseSync } = await import('node:sqlite');
+    const { DatabaseSync } = await loadSqlite();
     const filePath = sqlitePathFromUrl(url);
     const db = filePath === ':memory:' ? new DatabaseSync(':memory:') : new DatabaseSync(filePath, { readOnly: true });
     try {
@@ -408,7 +409,7 @@ async function sqliteFetch(url, entity, options) {
 }
 async function sqliteInsert(url, entity, record) {
     assertValidIdentifier(entity, 'table name');
-    const { DatabaseSync } = await import('node:sqlite');
+    const { DatabaseSync } = await loadSqlite();
     const filePath = sqlitePathFromUrl(url);
     const db = filePath === ':memory:' ? new DatabaseSync(':memory:') : new DatabaseSync(filePath);
     try {
@@ -452,7 +453,7 @@ async function sqliteInsert(url, entity, record) {
 }
 async function sqliteUpdate(url, entity, primaryKey, updates) {
     assertValidIdentifier(entity, 'table name');
-    const { DatabaseSync } = await import('node:sqlite');
+    const { DatabaseSync } = await loadSqlite();
     const filePath = sqlitePathFromUrl(url);
     const db = filePath === ':memory:' ? new DatabaseSync(':memory:') : new DatabaseSync(filePath);
     try {
@@ -482,7 +483,7 @@ async function sqliteUpdate(url, entity, primaryKey, updates) {
 }
 async function sqliteDelete(url, entity, primaryKey) {
     assertValidIdentifier(entity, 'table name');
-    const { DatabaseSync } = await import('node:sqlite');
+    const { DatabaseSync } = await loadSqlite();
     const filePath = sqlitePathFromUrl(url);
     const db = filePath === ':memory:' ? new DatabaseSync(':memory:') : new DatabaseSync(filePath);
     try {