@njeybe/nativ 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 2.6.0
+
+### Improved: token usage and autonomy
+
+- **Leaner directives.** `AGENTS.md` (-17%), `CLAUDE.md` (-20%) and the worker and verifier agents are shorter. Subagents no longer re-read `AGENTS.md`, which already reaches them through `CLAUDE.md`. The human-communication rules now live in one place.
+- **Compact JSON.** `task next`, `task list` and `triage --json` print single-line JSON. `recommendedContractSlice` is a bare file list.
+- **Brief task list over MCP.** `nativ_task_list` returns a short summary per task; pass `full: true` for every field.
+- **Self-healing ladder.** `AGENTS.md` and `CLAUDE.md` tell agents to retry, patch additively, then run `nativ triage --all --apply --json`; only `REQUIRE_HUMAN_DECISION` items, destructive changes, credentials and repeated failures reach the human.
+- **Resumable sessions.** The SessionStart orientation lists blocked tasks and pending escalations.
+- **Budget guard.** `tests/test-token-budget.mjs` fails when an always-loaded file outgrows its token budget.
+
+### Added
+
+- **Self-healing guide.** `docs/self-healing.md` explains the hands-free loop end to end: claims, the escalation ladder, reclaiming stuck tasks and notifications.
+- **`nativ_validate` MCP tool.** A read-only contract check for MCP hosts that returns only the problems and a verdict, not every passing line.
+- **Notifications when nativ needs you.** A `notify` webhook (Slack, Discord, ntfy, any JSON endpoint) or command in `.nativ/config.json` is called when triage returns `REQUIRE_HUMAN_DECISION` or the circuit breaker blocks a task, once per escalation. Webhooks must be https. `nativ notify test` sends a sample. Failures are recorded, never fatal.
+- **`nativ_triage` MCP tool.** Hosts that only speak MCP can now run the self-healing step: it evaluates pending escalations (or one), applies sandbox-proven additive fixes, and returns the decision card for items a person must decide. The directives and session orientation point to it.
+
+### Fixed
+
+- **Tasks are claimed, not just started.** `task start` refuses a completed or blocked task and one whose dependencies are unfinished, and records `claimedBy` (`--agent` or `NATIV_AGENT_ID`) and `claimedAt`. Another agent cannot start a task with a fresh claim; a claim older than 4 hours can be taken over. Complete and block release the claim. A person can override with `--force`. `nativ_task_start` takes an optional `agent`.
+- **Stuck tasks recover.** `nativ task reclaim` (and `nativ_task_reclaim`) returns `in_progress` tasks with a claim older than 4 hours (`--older-than`) to pending, so a crashed agent no longer leaves a task stuck forever. `--dry-run` reports only. The SessionStart orientation lists stale tasks, and the self-healing ladder covers them.
+- **Provider calls survive network blips.** A network failure or a 5xx answer from Claude API or Gemini is now a `TRANSIENT` error, retried on the same provider twice (about 0.5s and 1s, with jitter) before the chain moves to the next provider. Rejected requests and timeouts are not retried.
+- **Shared JSON files are written safely.** Contract patches, `.nativ/config.json`, task unlocks, provider cooldowns and runner records now go through one atomic writer that retries Windows sharing violations; contract patches no longer fail silently on Windows. Config and unlock changes are read-modify-written under a lock, so parallel writers keep each other's keys, and a config file that does not parse is left untouched instead of being wiped. Studio reports a failed triage-config save instead of claiming success.
+- **Locks wait as long everywhere and leave no empty files.** The plan lock now waits about 5s like the other locks (it gave up after about 0.4s), and locking a file that does not exist no longer creates an empty one that JSON readers cannot parse.
+- **Unknown escalation types are refused.** `nativ task escalate --type` used to turn a typo into `architectural_ambiguity` silently; it now lists the valid types and writes nothing. The CLI and MCP share one list.
+- **`nativ init` writes the architect guide.** It copied a fixed list of eight guides and skipped `architect.md`; it now copies every guide in the templates. `nativ validate` checks the architect guide when present.
+- **Windows paths in `.mcp.json` count as machine-specific on every OS.** A `C:/...` command was treated as portable when setup ran on Linux or macOS.
+- **Continuous integration.** `.github/workflows/ci.yml` builds, checks the plugin sync and runs every suite on Ubuntu (Node 20 and 22) and Windows (Node 22) for pushes to `main` and `dev` and for pull requests. The test runner clears `CI` and the headless overrides for each suite, so tests behave the same on a laptop and in CI.
+- **SQLite on Node 20 explains itself.** SQLite support uses `node:sqlite`, which ships with Node.js 22.5+. On Node 20 the database commands and Studio now say so plainly instead of failing with an unknown-module error. The contract-generator tests no longer depend on `node --test` glob support, which Node 20 lacks.
+- **`npm test` runs every suite.** `tests/run-all.mjs` keeps going after a failure and lists every failed suite at the end.
+
+## 2.5.1
+
+### Fixed
+
+- Added missing `architect` role guide (`templates/dot-ai/subagents/architect.md` and `.ai/subagents/architect.md`). `nativ doctor` no longer warns about the architect role having no guide.
+
 ## 2.5.0
 
 ### Added

package/README.md

@@ -152,6 +152,7 @@ Every command takes an optional `[targetDir]` (default: the current directory) a
 | [`task list`](#nativ-task-list) / `tasks` | List tasks with filters | You, Agent |
 | [`task add`](#nativ-task-add) | Add a task | Architect |
 | [`task start`](#nativ-task-start) | Mark a task in progress | Agent |
+| [`task reclaim`](#nativ-task-reclaim) | Free tasks left in progress by a stopped agent | You, Agent |
 | [`task complete`](#nativ-task-complete) | Complete a task through the gatekeeper | Agent |
 | [`task block`](#nativ-task-block) | Block a task with a reason | Agent |
 | [`task escalate`](#nativ-task-escalate) | Escalate a contract gap to the architect | Agent |
@@ -162,6 +163,7 @@ Every command takes an optional `[targetDir]` (default: the current directory) a
 | [`learn list`](#nativ-learn-list) | List lessons | You, Agent |
 | [`learn approve` / `reject`](#nativ-learn-approve--reject) | Decide on a lesson | *You only* |
 | [`triage`](#nativ-triage) | Evaluate pending escalations; decision cards for you | You |
+| [`notify test`](#nativ-notify-test) | Check the webhook or command that tells you a decision is waiting | You |
 | [`db status` / `inspect` / `diff`](#nativ-db-status--inspect--diff) | Masked, structure-only database checks | You, Agent |
 | [`db sync`](#nativ-db-sync) | Copy a live schema into `.ai/db_schema.json` | *You only* |
 | [`worktree create` / `list` / `merge` / `remove`](#nativ-worktree) | Isolated worktrees for parallel tasks | You, Agent |
@@ -361,10 +363,18 @@ nativ task add "Appointment list" -a frontend --complexity standard \
 #### `nativ task start`
 
 ```bash
-nativ task start <taskId> [targetDir]
+nativ task start <taskId> [targetDir] [--agent <id>] [--force]
 ```
 
-Marks the task `in_progress` and records the baseline the test-integrity guard compares against.
+Claims the task, marks it `in_progress` and records the baseline the test-integrity guard compares against. The task must be pending and its dependencies completed; a blocked task goes through `nativ triage` first, and only a person can override with `--force`. The claim records `claimedBy` (`--agent` or `$NATIV_AGENT_ID`) and `claimedAt`, so a parallel agent cannot take a task another agent holds. Running `task start` again on your own task refreshes the claim; a claim older than 4 hours counts as abandoned.
+
+#### `nativ task reclaim`
+
+```bash
+nativ task reclaim [taskId] [targetDir] [--older-than <hours>] [--dry-run] [--json]
+```
+
+Puts `in_progress` tasks whose agent stopped (a crash or a closed session) back to `pending`. Without a task id it reclaims every claim older than `--older-than` hours (default 4). Tasks started before claims were recorded have no claim time; name them to reclaim them. A fresh claim is refused unless a person passes `--force`. The SessionStart orientation lists stale tasks. The previous agent may have left partial changes, so review the working tree before restarting.
 
 #### `nativ task complete`
 
@@ -517,7 +527,7 @@ If the lesson changed while you were reviewing it, nothing is decided and you ar
 
 ### Escalations and triage
 
-A worker that finds a contract gap escalates (`nativ task escalate`) and stops. The gap is then resolved by the architect, or first assessed by triage.
+A worker that finds a contract gap escalates (`nativ task escalate`) and stops. The gap is then resolved by the architect, or first assessed by triage. [docs/self-healing.md](docs/self-healing.md) walks through the whole hands-free loop: claims, retries, triage, reclaiming stuck tasks and notifications.
 
 #### `nativ triage`
 
@@ -536,6 +546,16 @@ nativ triage [escalationId] [targetDir] [options]
 
 When an escalation is settled, its resolution notes reach the next worker on that task as `priorEscalations`.
 
+#### `nativ notify test`
+
+nativ can tell you when it needs you: when triage returns `REQUIRE_HUMAN_DECISION`, and when the circuit breaker blocks a task. Each escalation is announced once. Add a webhook (Slack, Discord, ntfy or any JSON endpoint) or a local command to `.nativ/config.json`, which git ignores, so a webhook token stays on your machine:
+
+```json
+{ "notify": { "webhook": "https://hooks.slack.com/services/...", "events": ["human_decision", "circuit_breaker_tripped"] } }
+```
+
+The webhook receives JSON with `text` (Slack, ntfy), `content` (Discord), and the task, escalation, question, options and next step as fields. Webhooks must use `https://` (plain `http://` only to `localhost`). A `"command"` receives the same JSON on stdin and in `NATIV_NOTIFY_JSON`, e.g. `"command": "notify-send nativ \"$(jq -r .text)\""`. `nativ notify test` sends a sample; delivery failures never stop the workflow and are recorded in `.nativ/notify-state.json`.
+
 [Back to contents](#contents)
 
 ---
@@ -665,12 +685,15 @@ Written by `setup`; every key is optional.
 | `codeStyle.maxCommentLines` | `2` | Longest allowed comment block |
 | `providers` | see [Providers](#providers) | Provider order per role: `architect`, `pm`, `worker`, `verifier`, `triage` |
 | `models` | provider default | Model per provider |
+| `notify` | off | `webhook`, `command` and `events` for human notifications. See [`nativ notify test`](#nativ-notify-test) |
 
 ### Environment variables
 
 | Variable | Used for |
 | :--- | :--- |
 | `NATIV_ROLE` | Session role; `NATIV_ROLE=architect` lets a whole session write `.ai/` |
+| `NATIV_AGENT_ID` | Who claims a task on `task start`, so parallel agents never take the same task |
+| `NATIV_NOTIFY_WEBHOOK`, `NATIV_NOTIFY_COMMAND` | Override the `notify` webhook or command from `.nativ/config.json` |
 | `ANTHROPIC_API_KEY` | The `claude-api` provider and the Studio native runner |
 | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | The `gemini` provider |
 | `NATIV_DEV_DATABASE_URL`, `DEV_DATABASE_URL`, `DATABASE_URL` | Dev database for `nativ db`, checked in that order, read from your `.env*` files. MongoDB (`MONGODB_URI`) and Firestore variants work too, and names declared in `.env.example` are checked first |
@@ -777,7 +800,9 @@ Files nativ wrote carry a marker, so `update` and `doctor` can tell untouched fi
 | Tools | Purpose |
 | :--- | :--- |
 | `nativ_task_next`, `nativ_task_list`, `nativ_task_add` | Find and add work |
-| `nativ_task_start`, `nativ_task_complete`, `nativ_task_block` | Move a task through its lifecycle (complete always runs the gatekeeper) |
+| `nativ_task_start`, `nativ_task_complete`, `nativ_task_block`, `nativ_task_reclaim` | Move a task through its lifecycle (complete always runs the gatekeeper; reclaim frees stale claims) |
+| `nativ_validate` | Check the `.ai/` contracts, plan and role guides; returns only problems and a verdict |
+| `nativ_triage` | Self-heal: evaluate pending escalations, apply sandbox-proven safe fixes, return decision cards for the rest |
 | `nativ_task_escalate`, `nativ_task_propose_patch` | Escalate a gap or propose a governed patch |
 | `nativ_learn_propose` | Propose a lesson; you approve it in a terminal |
 | `nativ_verify`, `nativ_status`, `nativ_bench`, `nativ_test_gen` | Verification, progress, benchmarks, test generation |

package/dist/commands/init.js

@@ -96,16 +96,8 @@ export async function runInit(targetDirArg, options = {}) {
         console.log(pc.green('✔ Created .ai/master_plan.json'));
     }
     // 7. Write Sub-agent specifications
-    const subagentFiles = [
-        'backend.md',
-        'frontend.md',
-        'database.md',
-        'qa-tester.md',
-        'flutter-developer.md',
-        'devops-agent.md',
-        'security-auditor.md',
-        'db-migration.md',
-    ];
+    const guidesDir = path.join(templatesDir, 'dot-ai/subagents');
+    const subagentFiles = fs.existsSync(guidesDir) ? fs.readdirSync(guidesDir).filter((f) => f.endsWith('.md')).sort() : [];
     for (const file of subagentFiles) {
         const src = path.join(templatesDir, 'dot-ai/subagents', file);
         const dest = path.join(subagentsDir, file);

package/dist/commands/notify.d.ts

@@ -0,0 +1,2 @@
+/** `nativ notify test`: sends a sample notification so a person can check the webhook or command works. */
+export declare function runNotifyTest(targetDirArg?: string): Promise<void>;

package/dist/commands/notify.js

@@ -0,0 +1,25 @@
+import pc from 'picocolors';
+import { resolveProjectRoot } from '../core/root-resolver.js';
+import { loadNotifyConfig, notifyHuman } from '../core/notify.js';
+/** `nativ notify test`: sends a sample notification so a person can check the webhook or command works. */
+export async function runNotifyTest(targetDirArg) {
+    const root = resolveProjectRoot(targetDirArg);
+    const config = loadNotifyConfig(root);
+    if (!config) {
+        console.log(pc.yellow('\nNotifications are off. Add to .nativ/config.json:'));
+        console.log(pc.white('  { "notify": { "webhook": "https://hooks.slack.com/services/..." } }'));
+        console.log(pc.dim('  or "command": "notify-send nativ \\"$(jq -r .text)\\"", or set NATIV_NOTIFY_WEBHOOK / NATIV_NOTIFY_COMMAND.\n'));
+        process.exitCode = 1;
+        return;
+    }
+    const result = await notifyHuman(root, { event: config.events[0], taskId: 'task-test', summary: 'This is a test notification from `nativ notify test`', question: 'Did it arrive?', options: ['Yes', 'No'] }, { force: true });
+    for (const e of result.errors)
+        console.error(pc.red(`✖ ${e}`));
+    if (result.sent) {
+        const via = [config.webhook && 'webhook', config.command && 'command'].filter(Boolean).join(' and ');
+        console.log(pc.green(`\n✔ Test notification sent via ${via}. Events: ${config.events.join(', ')}.\n`));
+    }
+    else {
+        process.exitCode = 1;
+    }
+}

package/dist/commands/session.d.ts

@@ -0,0 +1,22 @@
+import { SessionCheckpoint, SessionSummaryEntry } from '../core/session-memory.js';
+export interface SessionSaveOptions {
+    summary: string;
+    decision?: string[];
+    obstacle?: string[];
+    next?: string[];
+    activeFiles?: string;
+    task?: string;
+    role?: string;
+    sessionId?: string;
+    json?: boolean;
+}
+export interface SessionListOptions {
+    limit?: number;
+    json?: boolean;
+}
+export interface SessionGetOptions {
+    json?: boolean;
+}
+export declare function runSessionSave(targetDirArg?: string, options?: SessionSaveOptions): Promise<SessionCheckpoint>;
+export declare function runSessionList(targetDirArg?: string, options?: SessionListOptions): Promise<SessionSummaryEntry[]>;
+export declare function runSessionGet(sessionId?: string, targetDirArg?: string, options?: SessionGetOptions): Promise<SessionCheckpoint | null>;

package/dist/commands/session.js

@@ -0,0 +1,106 @@
+import path from 'node:path';
+import pc from 'picocolors';
+import { saveSessionCheckpoint, getLatestSession, getSession, listSessions, } from '../core/session-memory.js';
+export async function runSessionSave(targetDirArg, options = { summary: '' }) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const files = options.activeFiles
+        ? options.activeFiles.split(',').map((f) => f.trim()).filter(Boolean)
+        : undefined;
+    const checkpoint = saveSessionCheckpoint(targetDir, {
+        sessionId: options.sessionId,
+        summary: options.summary,
+        decisions: options.decision,
+        obstacles: options.obstacle,
+        nextSteps: options.next,
+        activeFiles: files,
+        taskId: options.task,
+        role: options.role,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(checkpoint, null, 2));
+        return checkpoint;
+    }
+    console.log(pc.bold(pc.green(`\n✔ Saved Session Checkpoint: `)) + pc.yellow(`[${checkpoint.sessionId}]`));
+    console.log(pc.bold('  Summary:    ') + pc.white(checkpoint.summary));
+    if (checkpoint.taskId) {
+        console.log(pc.bold('  Task:       ') + pc.yellow(checkpoint.taskId));
+    }
+    if (checkpoint.role) {
+        console.log(pc.bold('  Role:       ') + pc.magenta(checkpoint.role));
+    }
+    if (checkpoint.decisions && checkpoint.decisions.length > 0) {
+        console.log(pc.bold('  Decisions:  ') + pc.dim(checkpoint.decisions.join(' | ')));
+    }
+    if (checkpoint.obstacles && checkpoint.obstacles.length > 0) {
+        console.log(pc.bold('  Obstacles:  ') + pc.red(checkpoint.obstacles.join(' | ')));
+    }
+    if (checkpoint.nextSteps && checkpoint.nextSteps.length > 0) {
+        console.log(pc.bold('  Next Steps: ') + pc.cyan(checkpoint.nextSteps.join(' | ')));
+    }
+    if (checkpoint.activeFiles && checkpoint.activeFiles.length > 0) {
+        console.log(pc.bold('  Files:      ') + pc.dim(checkpoint.activeFiles.join(', ')));
+    }
+    console.log();
+    return checkpoint;
+}
+export async function runSessionList(targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const sessions = listSessions(targetDir, options.limit || 10);
+    if (options.json) {
+        console.log(JSON.stringify(sessions, null, 2));
+        return sessions;
+    }
+    console.log(pc.bold(pc.cyan('\nSession Memory Checkpoints (.ai/memory/sessions/)')));
+    console.log(pc.dim(`Workspace: ${targetDir}\n`));
+    if (sessions.length === 0) {
+        console.log(pc.dim('  No saved sessions found.\n'));
+        console.log(pc.dim('  Save current progress with: ') + pc.white('nativ session save --summary "..."\n'));
+        return sessions;
+    }
+    for (const s of sessions) {
+        const roleTag = s.role ? pc.magenta(`[${s.role}] `) : '';
+        const taskTag = s.taskId ? pc.yellow(`[${s.taskId}] `) : '';
+        console.log(`  ${pc.bold(pc.yellow(s.sessionId))} ${pc.dim(s.timestamp)} ${roleTag}${taskTag}\n    ${pc.white(s.summary)}`);
+    }
+    console.log();
+    return sessions;
+}
+export async function runSessionGet(sessionId, targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const session = sessionId ? getSession(targetDir, sessionId) : getLatestSession(targetDir);
+    if (options.json) {
+        console.log(JSON.stringify(session, null, 2));
+        return session;
+    }
+    if (!session) {
+        console.log(pc.yellow(`\nNo session found${sessionId ? ` matching [${sessionId}]` : ''}.\n`));
+        return null;
+    }
+    console.log(pc.bold(pc.cyan(`\nSession Details: `)) + pc.yellow(`[${session.sessionId}]`));
+    console.log(pc.bold('  Timestamp:  ') + pc.dim(session.timestamp));
+    if (session.taskId)
+        console.log(pc.bold('  Task ID:    ') + pc.yellow(session.taskId));
+    if (session.role)
+        console.log(pc.bold('  Role:       ') + pc.magenta(session.role));
+    console.log(pc.bold('  Summary:    ') + pc.white(session.summary));
+    if (session.decisions && session.decisions.length > 0) {
+        console.log(pc.bold('\n  Key Decisions:'));
+        for (const d of session.decisions)
+            console.log(pc.dim('   • ') + pc.white(d));
+    }
+    if (session.obstacles && session.obstacles.length > 0) {
+        console.log(pc.bold('\n  Obstacles / Blockers:'));
+        for (const o of session.obstacles)
+            console.log(pc.red('   ✖ ') + pc.white(o));
+    }
+    if (session.nextSteps && session.nextSteps.length > 0) {
+        console.log(pc.bold('\n  Next Steps:'));
+        for (const n of session.nextSteps)
+            console.log(pc.cyan('   → ') + pc.white(n));
+    }
+    if (session.activeFiles && session.activeFiles.length > 0) {
+        console.log(pc.bold('\n  Active Files: ') + pc.dim(session.activeFiles.join(', ')));
+    }
+    console.log();
+    return session;
+}

package/dist/commands/task/task-add.js

@@ -148,7 +148,7 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
             plan.overallStatus = 'in_progress';
         const result = { task, milestoneId: milestone.id, milestoneName: milestone.name, createdMilestone, reopenedMilestone };
         if (options.json) {
-            console.log(JSON.stringify(result, null, 2));
+            console.log(JSON.stringify(result));
             return result;
         }
         const track = fastPath ? pc.magenta(' [fast path]') : '';

package/dist/commands/task/task-common.js

@@ -24,22 +24,22 @@ export function getRoleGuide(assignedSubagent) {
 export function getRecommendedContractSlice(assignedSubagent) {
     const sub = assignedSubagent.toLowerCase();
     if (sub.includes('frontend') || sub.includes('flutter')) {
-        return '.ai/ui_specs.md (UI tokens & hierarchy) + .ai/api_contracts.json (Client endpoint integration)';
+        return '.ai/ui_specs.md + .ai/api_contracts.json';
     }
     if (sub.includes('backend')) {
-        return '.ai/api_contracts.json (Endpoint routes, request/response schemas) + .ai/db_schema.json (Models)';
+        return '.ai/api_contracts.json + .ai/db_schema.json';
     }
     if (sub.includes('database') || sub.includes('db-migration')) {
-        return '.ai/db_schema.json (Database schema contract & models)';
+        return '.ai/db_schema.json';
     }
     if (sub.includes('devops')) {
-        return '.ai/context.md (Infrastructure, runtime & deployment guardrails)';
+        return '.ai/context.md';
     }
     if (sub.includes('security')) {
-        return 'Target files & dependency manifests (.ai/context.md security guardrails)';
+        return 'targetFiles + dependency manifests + .ai/context.md';
     }
     if (sub.includes('qa')) {
-        return 'Target files, .ai/api_contracts.json, and verification test suite';
+        return 'targetFiles + .ai/api_contracts.json';
     }
     return '.ai/context.md';
 }

package/dist/commands/task/task-escalate.js

@@ -1,9 +1,17 @@
 import path from 'node:path';
 import pc from 'picocolors';
+import { ESCALATION_TYPES, } from '../../scanner/types.js';
 import { ContractGovernor, appendEscalation, } from '../../governor/index.js';
 import { withPlanLock } from '../../core/lock-manager.js';
 import { getPlanPath } from './task-common.js';
 export async function runTaskEscalate(taskId, targetDirArg, options = {}) {
+    const requestedType = options.type?.trim();
+    if (requestedType && !ESCALATION_TYPES.includes(requestedType)) {
+        console.error(pc.red(`\n✖ Unknown escalation type "${requestedType}". Use one of: ${ESCALATION_TYPES.join(', ')}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const escType = (requestedType || 'architectural_ambiguity');
     const { targetDir, planPath } = getPlanPath(targetDirArg);
     return withPlanLock(planPath, (plan, ctx) => {
         let foundTask = null;
@@ -20,16 +28,6 @@ export async function runTaskEscalate(taskId, targetDirArg, options = {}) {
             process.exitCode = 1;
             return;
         }
-        const validTypes = [
-            'contract_drift',
-            'schema_flaw',
-            'missing_credential',
-            'dependency_conflict',
-            'architectural_ambiguity',
-        ];
-        const escType = (options.type && validTypes.includes(options.type))
-            ? options.type
-            : 'architectural_ambiguity';
         const affectedContracts = options.affected
             ? options.affected.split(',').map((s) => s.trim())
             : ['.ai/db_schema.json', '.ai/api_contracts.json'];

package/dist/commands/task/task-lifecycle.d.ts

@@ -1,5 +1,11 @@
 import { TaskUnlockOptions, TaskCompleteOptions } from './task-common.js';
-export declare function runTaskStart(taskId: string, targetDirArg?: string): Promise<void | null>;
+export interface TaskStartOptions {
+    /** Who claims the task; defaults to NATIV_AGENT_ID. */
+    agent?: string;
+    /** Human override: start a blocked task or one whose dependencies are unfinished. */
+    force?: boolean;
+}
+export declare function runTaskStart(taskId: string, targetDirArg?: string, options?: TaskStartOptions): Promise<void | null>;
 export declare function runTaskUnlock(taskId: string, targetDirArg?: string, options?: TaskUnlockOptions): Promise<void>;
 export declare function runTaskComplete(taskId: string, targetDirArg?: string, options?: TaskCompleteOptions): Promise<void>;
 export declare function runTaskBlock(taskId: string, reason: string, targetDirArg?: string): Promise<void | null>;

package/dist/commands/task/task-lifecycle.js

@@ -1,13 +1,18 @@
 import pc from 'picocolors';
 import { runTaskVerification } from '../../core/verifier.js';
+import { digestFailure } from '../../core/verifier/output-digest.js';
 import { CircuitBreaker, TestIntegrityGuard, resolveGitHead, closeEscalationsForTask, } from '../../governor/index.js';
 import { loadPlan, withPlanLock } from '../../core/lock-manager.js';
 import { recordTaskStart, recordTaskComplete } from '../../core/telemetry.js';
 import { addTaskUnlock, removeTaskUnlock } from '../../core/enforcement.js';
 import { refuseHeadless } from '../../core/human-gate.js';
+import { resolveAgentId, startRefusal } from '../../core/task-claims.js';
 import { getPlanPath, } from './task-common.js';
-export async function runTaskStart(taskId, targetDirArg) {
+export async function runTaskStart(taskId, targetDirArg, options = {}) {
+    if (options.force && refuseHeadless('nativ task start --force'))
+        return;
     const { targetDir, planPath } = getPlanPath(targetDirArg);
+    const agent = resolveAgentId(options.agent);
     return withPlanLock(planPath, async (plan, ctx) => {
         let foundTask = null;
         let foundMilestone = null;
@@ -25,7 +30,20 @@ export async function runTaskStart(taskId, targetDirArg) {
             process.exitCode = 1;
             return;
         }
+        const refusal = options.force ? null : startRefusal(plan, foundTask, agent);
+        if (refusal) {
+            ctx.abort();
+            console.error(pc.red(`\n✖ ${refusal}\n`));
+            process.exitCode = 1;
+            return;
+        }
+        const resumed = foundTask.status === 'in_progress';
         foundTask.status = 'in_progress';
+        foundTask.claimedAt = new Date().toISOString();
+        if (agent)
+            foundTask.claimedBy = agent;
+        else if (!resumed)
+            delete foundTask.claimedBy;
         if (foundMilestone.status === 'pending') {
             foundMilestone.status = 'in_progress';
         }
@@ -134,17 +152,20 @@ export async function runTaskComplete(taskId, targetDirArg, options = {}) {
             if (failedPhase)
                 console.error(pc.yellow(`  Phase:   ${failedPhase.name}`));
             console.error(pc.yellow(`  Command: \`${vResult.command}\``));
-            if (vResult.stderr && vResult.stderr.trim()) {
+            const digest = digestFailure(targetDir, taskId, vResult);
+            if (digest.stderr) {
                 console.error(pc.red('\n--- stderr ---'));
-                console.error(pc.red(vResult.stderr.trim()));
+                console.error(pc.red(digest.stderr));
             }
-            if (vResult.stdout && vResult.stdout.trim() && !vResult.stderr?.trim()) {
+            if (digest.stdout) {
                 console.error(pc.dim('\n--- stdout ---'));
-                console.error(pc.dim(vResult.stdout.trim()));
+                console.error(pc.dim(digest.stdout));
             }
             if (vResult.error && !vResult.stderr?.includes(vResult.error)) {
                 console.error(pc.red(`\nError: ${vResult.error}`));
             }
+            if (digest.logFile)
+                console.error(pc.dim(`\n  Full output: ${digest.logFile}`));
             console.error(pc.yellow(`\n⚠ Task remains '${foundTask.status}'. Fix the issue and retry:`));
             console.error(pc.white(`  nativ task complete ${taskId}`));
             console.error(pc.dim('  (or pass --no-verify to bypass verification check)\n'));
@@ -189,6 +210,8 @@ export async function runTaskComplete(taskId, targetDirArg, options = {}) {
             return;
         }
         taskToComplete.status = 'completed';
+        delete taskToComplete.claimedBy;
+        delete taskToComplete.claimedAt;
         if (options.notes) {
             taskToComplete.notes = options.notes;
         }
@@ -246,6 +269,8 @@ export async function runTaskBlock(taskId, reason, targetDirArg) {
         }
         foundTask.status = 'blocked';
         foundTask.notes = reason.trim();
+        delete foundTask.claimedBy;
+        delete foundTask.claimedAt;
         console.log(pc.yellow(`\n⚠ Task [${pc.bold(taskId)}] marked as `) + pc.red('✖ blocked'));
         console.log(pc.dim(`  Reason: ${foundTask.notes}\n`));
     });

package/dist/commands/task/task-query.d.ts

@@ -4,6 +4,8 @@ export declare function runTaskList(targetDirArg?: string, options?: {
     milestone?: string;
     fastPath?: boolean;
     json?: boolean;
+    /** JSON only: id, title, status, role, dependencies and files; leaves out long prose fields. */
+    brief?: boolean;
 }): Promise<void>;
 export declare function runTaskNext(targetDirArg?: string, options?: {
     json?: boolean;

package/dist/commands/task/task-query.js

@@ -48,15 +48,17 @@ export async function runTaskList(targetDirArg, options = {}) {
         }
     }
     if (options.json) {
-        const jsonOutput = results.map(({ task, milestoneId, milestoneName, isAvailable }) => ({
-            ...task,
-            milestoneId,
-            milestoneName,
-            isAvailable,
-            roleGuide: getRoleGuide(task.assignedSubagent),
-            contractSlice: getRecommendedContractSlice(task.assignedSubagent),
-        }));
-        console.log(JSON.stringify(jsonOutput, null, 2));
+        const jsonOutput = results.map(({ task, milestoneId, milestoneName, isAvailable }) => options.brief
+            ? briefTask(task, milestoneId, isAvailable)
+            : {
+                ...task,
+                milestoneId,
+                milestoneName,
+                isAvailable,
+                roleGuide: getRoleGuide(task.assignedSubagent),
+                contractSlice: getRecommendedContractSlice(task.assignedSubagent),
+            });
+        console.log(JSON.stringify(jsonOutput));
         return;
     }
     console.log(pc.bold(pc.cyan(`\n📋 nativ Tasks: ${plan.projectName}`)));
@@ -108,6 +110,19 @@ export async function runTaskList(targetDirArg, options = {}) {
         pc.gray(`${pendingCount} pending`) + pc.dim(', ') +
         pc.red(`${blockedCount} blocked`) + '\n');
 }
+function briefTask(t, milestoneId, isAvailable) {
+    return {
+        id: t.id,
+        title: t.title,
+        status: t.status,
+        role: t.assignedSubagent,
+        milestoneId,
+        isAvailable,
+        ...(t.dependencies?.length ? { dependencies: t.dependencies } : {}),
+        ...(t.targetFiles?.length ? { targetFiles: t.targetFiles } : {}),
+        ...(t.status === 'blocked' && t.notes ? { notes: t.notes } : {}),
+    };
+}
 /** What a worker needs from a lesson; status and audit fields stay in .ai/learnings.json. */
 function toTaskLearning({ id, insight, details, files }) {
     return { id, insight, ...(details ? { details } : {}), ...(files ? { files } : {}) };
@@ -168,7 +183,7 @@ export async function runTaskNext(targetDirArg, options = {}) {
         }
         if (!activeMilestone) {
             if (options.json) {
-                console.log(JSON.stringify({ status: 'all_milestones_completed', activeTask: null }, null, 2));
+                console.log(JSON.stringify({ status: 'all_milestones_completed', activeTask: null }));
             }
             else {
                 console.log(pc.bold(pc.green('\n🎉 All milestones and tasks are completed!\n')));
@@ -196,7 +211,7 @@ export async function runTaskNext(targetDirArg, options = {}) {
                     milestoneId: activeMilestone.id,
                     milestoneName: activeMilestone.name,
                     activeTask: null,
-                }, null, 2));
+                }));
             }
             else {
                 if (hasBlocked) {
@@ -233,7 +248,7 @@ export async function runTaskNext(targetDirArg, options = {}) {
                 ...(learnings.length ? { learnings: learnings.map(toTaskLearning) } : {}),
                 ...(priorEscalations.length ? { priorEscalations } : {}),
             }
-        }, null, 2));
+        }));
         return;
     }
     const fastTag = targetTask.fastPath ? pc.cyan(' [FAST-PATH PRIORITY]') : '';

package/dist/commands/task/task-reclaim.d.ts

@@ -0,0 +1,20 @@
+export interface TaskReclaimOptions {
+    /** Claims at least this many hours old are abandoned (default 4). */
+    olderThan?: number;
+    dryRun?: boolean;
+    json?: boolean;
+    /** Human override: reclaim a named task even though its claim is fresh. */
+    force?: boolean;
+}
+export interface ReclaimedTask {
+    id: string;
+    claimedBy?: string;
+    ageHours: number | null;
+}
+export interface TaskReclaimResult {
+    reclaimed: ReclaimedTask[];
+    /** in_progress tasks with no claim time (started before claims existed): reclaim them by id. */
+    unknownAge: string[];
+}
+/** Puts in_progress tasks whose agent stopped (crash, closed session) back to pending so another agent can take them. */
+export declare function runTaskReclaim(taskId?: string, targetDirArg?: string, options?: TaskReclaimOptions): Promise<TaskReclaimResult | null>;