nubos-pilot 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to nubos-pilot are documented in this file. Format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
 follows [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.3] — 2026-06-24
+
+A finished milestone can no longer block the start of the next one with a stale checkpoint.
+
+- `init resume-work` now reconciles every checkpoint against git before deciding orphan: a checkpoint whose task already has a `task(<id>):` commit is a tombstone left behind when the checkpoint was never unlinked (a crash between commit and unlink, or a commit made outside `commit-task`). Those are pruned silently and reported in `pruned_checkpoints`; only genuinely uncommitted checkpoints still surface as `orphan`. Git is the source of truth, so a committed task is never mistaken for in-flight work.
+- `np:doctor` is git-aware for the same case: a committed-but-unlinked checkpoint is reported as `info` / `fixable: auto` with the commit sha, not as a manual-fix `warn`.
+- The `execute-phase` orphan-checkpoint guard's two remediation options are now wired — "reset-slice" and "resume" were previously no-op `case` branches that left the file in place, so the prompt re-fired on every run.
+
+Full documentation at <https://pilot.nubos.cloud>.
+
 ## [1.3.0] — 2026-06-17
 
 Run any agent on any model, not only Claude.

package/bin/np-tools/doctor.cjs

@@ -543,6 +543,28 @@ function _checkOrphanCheckpoints(projectRoot) {
     catch { continue; }
     if (!cp || cp.status !== 'in-progress') continue;
     if (currentTask === taskId) continue;
+
+    let committedSha = null;
+    try { committedSha = require('../../lib/checkpoint-reconcile.cjs').committedSha(taskId, projectRoot); }
+    catch { committedSha = null; }
+
+    if (committedSha) {
+      issues.push({
+        id: 'orphan-checkpoint',
+        severity: 'info',
+        fixable: 'auto',
+        details: {
+          task_id: taskId,
+          checkpoint: path.relative(projectRoot, cpPath),
+          current_task: currentTask,
+          committed_sha: committedSha,
+          hint: 'Task is already committed (' + committedSha.slice(0, 8) + ') but its checkpoint was never unlinked. '
+            + 'A stale tombstone, not in-flight work. `np-tools resume-work` reconciles it against git and prunes it automatically.',
+        },
+      });
+      continue;
+    }
+
     issues.push({
       id: 'orphan-checkpoint',
       severity: 'warn',
@@ -551,9 +573,9 @@ function _checkOrphanCheckpoints(projectRoot) {
         task_id: taskId,
         checkpoint: path.relative(projectRoot, cpPath),
         current_task: currentTask,
-        hint: 'Checkpoint marks task as in-progress but STATE.md.current_task does not match. '
-          + 'Likely a crash during finishTask between STATE-clear and checkpoint-unlink. '
-          + 'Run `np-tools undo-task ' + taskId + '` to clean up, or delete manually after verifying the task is genuinely done.',
+        hint: 'Checkpoint marks task as in-progress, no matching commit exists, and STATE.md.current_task does not match. '
+          + 'Likely a genuine crash mid-flight. '
+          + 'Run `np-tools undo-task ' + taskId + '` to clean up, or resume the task, after verifying its state.',
       },
     });
   }

package/bin/np-tools/resume-work.cjs

@@ -3,6 +3,7 @@ const path = require('node:path');
 const { NubosPilotError } = require('../../lib/core.cjs');
 const { readState } = require('../../lib/state.cjs');
 const { readCheckpoint, listCheckpoints } = require('../../lib/checkpoint.cjs');
+const { reconcileCommittedCheckpoints } = require('../../lib/checkpoint-reconcile.cjs');
 const { TASK_ID_RE } = require('../../lib/ids.cjs');
 const textMode = require('../../lib/text-mode.cjs');
 const layout = require('../../lib/layout.cjs');
@@ -48,6 +49,12 @@ function run(_args, ctx) {
 
   const state = _safeReadState(cwd);
   const currentTask = state && state.frontmatter ? state.frontmatter.current_task : null;
+
+  let pruned = [];
+  try {
+    pruned = reconcileCommittedCheckpoints(cwd, { exclude: currentTask }).pruned;
+  } catch { pruned = []; }
+
   const cpFiles = listCheckpoints(cwd);
 
   let payload;
@@ -104,6 +111,8 @@ function run(_args, ctx) {
     };
   }
 
+  if (pruned.length > 0) payload.pruned_checkpoints = pruned;
+
   const tmDetail = textMode.resolveTextModeDetail(cwd);
   payload.text_mode = tmDetail.enabled;
   payload.text_mode_source = tmDetail.source;

package/bin/np-tools/resume-work.test.cjs

@@ -3,9 +3,10 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const { execFileSync } = require('node:child_process');
 
 const subcmd = require('./resume-work.cjs');
-const { startTask } = require('../../lib/checkpoint.cjs');
+const { startTask, listCheckpoints } = require('../../lib/checkpoint.cjs');
 
 const _roots = [];
 
@@ -78,6 +79,25 @@ test('RW-3: orphan when checkpoint files exist but no matching STATE.current_tas
   assert.ok(p.checkpoint_ids.includes('M006-S001-T0005'));
 });
 
+test('RW-5: committed orphan is reconciled against git and pruned (not surfaced)', () => {
+  const root = makeRoot(null);
+  execFileSync('git', ['init', '-q', '-b', 'main', root], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'chore: init'], { stdio: 'pipe' });
+  startTask({ id: 'M013-S005-T0002', phase: 6, plan: '06-01', wave: 1 }, root);
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'task(M013-S005-T0002): demo'], { stdio: 'pipe' });
+  const statePath = path.join(root, '.nubos-pilot', 'STATE.md');
+  fs.writeFileSync(statePath, fs.readFileSync(statePath, 'utf-8').replace(/current_task:.*/, 'current_task: null'), 'utf-8');
+
+  const cap = _capture();
+  const p = subcmd.run([], { cwd: root, stdout: cap.stub });
+  assert.equal(p.status, 'clean');
+  assert.ok(Array.isArray(p.pruned_checkpoints));
+  assert.equal(p.pruned_checkpoints[0].task_id, 'M013-S005-T0002');
+  assert.deepEqual(listCheckpoints(root), []);
+});
+
 test('RW-4: malformed checkpoint → checkpoint-schema-mismatch (T-06-12)', () => {
   const root = makeRoot('M006-S001-T0009');
   const cpDir = path.join(root, '.nubos-pilot', 'checkpoints');

package/lib/checkpoint-reconcile.cjs

@@ -0,0 +1,42 @@
+const path = require('node:path');
+const { listCheckpoints, deleteCheckpoint } = require('./checkpoint.cjs');
+const { findCommitByTaskId } = require('./git.cjs');
+const { TASK_ID_RE } = require('./ids.cjs');
+
+function committedSha(taskId, cwd) {
+  try {
+    return findCommitByTaskId(taskId, cwd);
+  } catch {
+    return null;
+  }
+}
+
+function reconcileCommittedCheckpoints(cwd = process.cwd(), opts = {}) {
+  const exclude = opts.exclude || null;
+  const pruned = [];
+  const remaining = [];
+  for (const file of listCheckpoints(cwd)) {
+    const taskId = path.basename(file, '.json');
+    if (!TASK_ID_RE.test(taskId)) {
+      remaining.push(taskId);
+      continue;
+    }
+    if (exclude && taskId === exclude) {
+      remaining.push(taskId);
+      continue;
+    }
+    const sha = committedSha(taskId, cwd);
+    if (sha) {
+      deleteCheckpoint(taskId, cwd);
+      pruned.push({ task_id: taskId, sha });
+    } else {
+      remaining.push(taskId);
+    }
+  }
+  return { pruned, remaining };
+}
+
+module.exports = {
+  committedSha,
+  reconcileCommittedCheckpoints,
+};

package/lib/checkpoint-reconcile.test.cjs

@@ -0,0 +1,106 @@
+const { test, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync } = require('node:child_process');
+
+const { startTask, listCheckpoints } = require('./checkpoint.cjs');
+const { reconcileCommittedCheckpoints, committedSha } = require('./checkpoint-reconcile.cjs');
+
+const _repos = [];
+
+function makeRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-cr-'));
+  execFileSync('git', ['init', '-q', '-b', 'main', root], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'chore: init'], { stdio: 'pipe' });
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), `---
+schema_version: 2
+milestone: m1
+milestone_name: m1
+current_phase: null
+current_plan: null
+current_task: null
+last_updated: "2026-04-15T00:00:00Z"
+progress:
+  total_phases: 0
+  completed_phases: 0
+  total_plans: 0
+  completed_plans: 0
+  percent: 0
+session:
+  stopped_at: null
+  resume_file: null
+  last_activity: null
+---
+
+# State
+`, 'utf-8');
+  _repos.push(root);
+  return root;
+}
+
+function commitFor(root, taskId) {
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', `task(${taskId}): demo`], { stdio: 'pipe' });
+}
+
+after(() => {
+  while (_repos.length) {
+    const r = _repos.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('CR-1: prunes a checkpoint whose task already has a commit', () => {
+  const root = makeRepo();
+  startTask({ id: 'M013-S005-T0002', phase: 6, plan: '06-01', wave: 1 }, root);
+  commitFor(root, 'M013-S005-T0002');
+
+  const { pruned, remaining } = reconcileCommittedCheckpoints(root);
+  assert.equal(pruned.length, 1);
+  assert.equal(pruned[0].task_id, 'M013-S005-T0002');
+  assert.match(pruned[0].sha, /^[0-9a-f]{40}$/);
+  assert.deepEqual(remaining, []);
+  assert.deepEqual(listCheckpoints(root), []);
+});
+
+test('CR-2: keeps a checkpoint with no matching commit (genuine orphan)', () => {
+  const root = makeRepo();
+  startTask({ id: 'M013-S005-T0003', phase: 6, plan: '06-01', wave: 1 }, root);
+
+  const { pruned, remaining } = reconcileCommittedCheckpoints(root);
+  assert.deepEqual(pruned, []);
+  assert.deepEqual(remaining, ['M013-S005-T0003']);
+  assert.equal(listCheckpoints(root).length, 1);
+});
+
+test('CR-3: excludes the active current_task even when committed', () => {
+  const root = makeRepo();
+  startTask({ id: 'M013-S005-T0004', phase: 6, plan: '06-01', wave: 1 }, root);
+  commitFor(root, 'M013-S005-T0004');
+
+  const { pruned, remaining } = reconcileCommittedCheckpoints(root, { exclude: 'M013-S005-T0004' });
+  assert.deepEqual(pruned, []);
+  assert.deepEqual(remaining, ['M013-S005-T0004']);
+  assert.equal(listCheckpoints(root).length, 1);
+});
+
+test('CR-4: prunes committed tombstone but keeps uncommitted sibling', () => {
+  const root = makeRepo();
+  startTask({ id: 'M013-S005-T0002', phase: 6, plan: '06-01', wave: 1 }, root);
+  startTask({ id: 'M013-S005-T0003', phase: 6, plan: '06-01', wave: 1 }, root);
+  commitFor(root, 'M013-S005-T0002');
+
+  const { pruned, remaining } = reconcileCommittedCheckpoints(root);
+  assert.deepEqual(pruned.map((p) => p.task_id), ['M013-S005-T0002']);
+  assert.deepEqual(remaining, ['M013-S005-T0003']);
+});
+
+test('CR-5: committedSha returns null outside a git repo (no throw)', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-cr-nogit-'));
+  _repos.push(root);
+  assert.equal(committedSha('M013-S005-T0002', root), null);
+});

package/lib/git.cjs

@@ -92,7 +92,7 @@ function commitTask(taskId, files, message) {
   };
 }
 
-function findCommitByTaskId(id) {
+function findCommitByTaskId(id, cwd) {
   if (typeof id !== 'string' || !TASK_ID_RE.test(id)) {
     throw new NubosPilotError(
       'task-commit-not-found',
@@ -101,6 +101,8 @@ function findCommitByTaskId(id) {
     );
   }
 
+  const spawnOpts = { encoding: 'utf-8', timeout: GIT_TIMEOUT_MS };
+  if (cwd) spawnOpts.cwd = cwd;
   const out = execFileSync(
     'git',
     [
@@ -112,7 +114,7 @@ function findCommitByTaskId(id) {
       '1',
       '--format=%H',
     ],
-    { encoding: 'utf-8', timeout: GIT_TIMEOUT_MS },
+    spawnOpts,
   ).trim();
   if (!out) {
     throw new NubosPilotError(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubos-pilot",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Self-hosted AI pilot for any codebase. Researcher and critic agents plan, execute and verify each change.",
   "homepage": "https://pilot.nubos.cloud",
   "repository": {

package/workflows/execute-phase.md

@@ -118,16 +118,17 @@ If zero skills match, omit the block — do **not** invent skills. Adding new sk
 
 ## Pre-Flight — orphan-checkpoint guard
 
-Detect stale checkpoints from a prior run before starting new work:
+Detect stale checkpoints from a prior run before starting new work. `init resume-work` first **reconciles every checkpoint against git** (`lib/checkpoint-reconcile.cjs`): any checkpoint whose task already has a `task(<id>):` commit is a tombstone (finishTask never unlinked it — crash between commit and unlink, or a commit made outside `commit-task`) and is pruned silently. They surface in `RESUME.pruned_checkpoints` for the log, never as a prompt. Only genuinely **uncommitted** checkpoints reach `status: orphan` and the dialog below — so a finished milestone can never block the next one.
 
 ```bash
 RESUME=$(node .nubos-pilot/bin/np-tools.cjs init resume-work)
 RESUME_STATUS=$(echo "$RESUME" | node -e "process.stdin.on('data', d => console.log(JSON.parse(d).status))")
 if [ "$RESUME_STATUS" = "orphan" ]; then
+  ORPHAN_ID=$(echo "$RESUME" | node -e "process.stdin.on('data', d => { const p = JSON.parse(d); console.log((p.checkpoint_ids || [])[0] || '') })")
   CHOICE=$(node .nubos-pilot/bin/np-tools.cjs askuser --json '{
     "type": "select",
     "header": "Verwaiste Checkpoints gefunden",
-    "question": "Vor dem Milestone-Start wurden Checkpoint-Dateien ohne passenden STATE.current_task gefunden. Was tun?",
+    "question": "Vor dem Milestone-Start wurde ein uncommitteter Checkpoint ohne passenden STATE.current_task gefunden (kein zugehöriger Commit). Was tun?",
     "options": [
       {"label": "Clean working tree (reset-slice)", "description": "Verwirft die in-flight Task und löscht ihren Checkpoint."},
       {"label": "Resume the orphan task",            "description": "Setzt STATE.current_task auf den Checkpoint-Eintrag und spawnt den Executor."},
@@ -135,6 +136,13 @@ if [ "$RESUME_STATUS" = "orphan" ]; then
     ]
   }')
   case "$CHOICE" in
+    "Clean working tree (reset-slice)")
+      node .nubos-pilot/bin/np-tools.cjs reset-slice "$ORPHAN_ID"
+      ;;
+    "Resume the orphan task")
+      echo "execute-phase: resuming orphan task $ORPHAN_ID — run /np:resume-work" >&2
+      exit 0
+      ;;
     "Abort") exit 0 ;;
   esac
 fi