nubos-pilot 1.1.3 → 1.2.0

package/bin/np-tools/discuss-phase.cjs

@@ -1,17 +1,13 @@
 'use strict';
 
 const fs = require('node:fs');
-const path = require('node:path');
-const os = require('node:os');
-const crypto = require('node:crypto');
 
-const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { emitInitPayload } = require('../../lib/init-emit.cjs');
 const { getPhase } = require('../../lib/roadmap.cjs');
 const layout = require('../../lib/layout.cjs');
 const textMode = require('../../lib/text-mode.cjs');
 
-const INLINE_THRESHOLD_BYTES = 16 * 1024;
-
 function _parseArgs(args) {
   const rest = [];
   const flags = { assumptions: false };
@@ -51,25 +47,6 @@ function _agentSkills() {
   return { planner: null };
 }
 
-function _emit(payload, stdout, cwd) {
-  const json = JSON.stringify(payload, null, 2);
-  if (Buffer.byteLength(json, 'utf-8') <= INLINE_THRESHOLD_BYTES) {
-    stdout.write(json);
-    return;
-  }
-  let tmpDir;
-  try {
-    tmpDir = path.join(projectStateDir(cwd), '.tmp');
-    fs.mkdirSync(tmpDir, { recursive: true });
-  } catch (_err) {
-    tmpDir = os.tmpdir();
-  }
-  const suffix = process.pid + '-' + crypto.randomBytes(4).toString('hex');
-  const tmpPath = path.join(tmpDir, 'init-discuss-phase-' + suffix + '.json');
-  fs.writeFileSync(tmpPath, json, 'utf-8');
-  stdout.write('@file:' + tmpPath);
-}
-
 function run(args, ctx) {
   const context = ctx || {};
   const cwd = context.cwd || process.cwd();
@@ -117,8 +94,8 @@ function run(args, ctx) {
     agent_skills: _agentSkills(),
   };
 
-  _emit(payload, stdout, cwd);
+  emitInitPayload(payload, stdout, cwd, 'discuss-phase');
   return payload;
 }
 
-module.exports = { run, _parseArgs, _validateMilestoneArg, INLINE_THRESHOLD_BYTES };
+module.exports = { run, _parseArgs, _validateMilestoneArg };

package/bin/np-tools/doctor.cjs

@@ -5,6 +5,7 @@ const os = require('node:os');
 const path = require('node:path');
 
 const { NubosPilotError, atomicWriteFileSync } = require('../../lib/core.cjs');
+const { safeYamlParse } = require('../../lib/yaml.cjs');
 const manifestMod = require('../../lib/install/manifest.cjs');
 const codexTomlMod = require('../../lib/install/codex-toml.cjs');
 const runtimeAssetsMod = require('../../lib/install/runtime-assets.cjs');
@@ -20,14 +21,16 @@ const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
 const OPENCODE_LOCAL_PREFIX = '.opencode/nubos-pilot/';
 
 function _readScope(projectRoot) {
-  const cfgPath = path.join(projectRoot, STATE_SUBPATH, 'config.json');
-  if (!fs.existsSync(cfgPath)) return 'local';
+  const { readConfig, _CONFIG_PARSE_CODES } = require('../../lib/config.cjs');
+  let cfg;
   try {
-    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
-    return cfg && cfg.scope === 'global' ? 'global' : 'local';
-  } catch {
-    return 'local';
+    cfg = readConfig(projectRoot);
+  } catch (err) {
+    if (err && err.code === 'not-in-project') return 'local';
+    if (err && _CONFIG_PARSE_CODES.has(err.code)) return 'local';
+    throw err;
   }
+  return cfg && cfg.scope === 'global' ? 'global' : 'local';
 }
 
 function _payloadBaseFor(projectRoot, scope) {
@@ -281,8 +284,7 @@ function _checkMilestoneLayout(projectRoot) {
   if (!fs.existsSync(roadmapPath)) return [];
   let doc;
   try {
-    const YAML = require('yaml');
-    doc = YAML.parse(fs.readFileSync(roadmapPath, 'utf-8'));
+    doc = safeYamlParse(fs.readFileSync(roadmapPath, 'utf-8'), { kind: 'doctor-roadmap' });
   } catch {
     return [{
       id: 'roadmap-unreadable',
@@ -321,7 +323,6 @@ function _checkMilestoneLayout(projectRoot) {
     }
   }
 
-  // Flag old .nubos-pilot/phases/ dir as stale if still present
   const phasesDir = path.join(stateDir, 'phases');
   if (fs.existsSync(phasesDir)) {
     issues.push({
@@ -337,10 +338,6 @@ function _checkMilestoneLayout(projectRoot) {
   return issues;
 }
 
-// Single-critic revision (ADR-0010 §Single-Critic Revision 2026-05-05): one
-// np-critic spawned per round, with three audit-surface modules loaded as
-// <files_to_read>. The doctor checks that all four files are present —
-// missing the spawnable critic OR any of the three modules breaks the loop.
 const NUBOSLOOP_CRITICS = [
   'np-critic',             // spawnable (sonnet)
   'np-critic-style',       // axis module (Style)
@@ -426,10 +423,28 @@ function _checkNubosloopKnowledgeStore(projectRoot) {
 
 function _checkNubosloopConfig(projectRoot) {
   const issues = [];
-  const cfgPath = path.join(projectRoot, '.nubos-pilot', 'config.json');
-  if (!fs.existsSync(cfgPath)) return issues;
+  const { readConfig, _CONFIG_PARSE_CODES } = require('../../lib/config.cjs');
   let cfg;
-  try { cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')); } catch { return issues; }
+  try {
+    cfg = readConfig(projectRoot);
+  } catch (err) {
+    if (err && err.code === 'not-in-project') return issues;
+    if (err && _CONFIG_PARSE_CODES.has(err.code)) {
+      issues.push({
+        id: 'config-json-corrupt',
+        severity: 'error',
+        fixable: 'manual',
+        details: {
+          code: err.code,
+          message: err.message,
+          file: err.details && err.details.file,
+          hint: 'Repair or delete .nubos-pilot/config.json — the file is unparseable or has the wrong shape.',
+        },
+      });
+      return issues;
+    }
+    throw err;
+  }
   const swarm = cfg && cfg.swarm;
   const adapter = swarm && swarm.knowledge_adapter;
   if (adapter && adapter !== 'local') {
@@ -488,6 +503,50 @@ function _checkOrphanTmpFiles(projectRoot) {
   return issues;
 }
 
+function _checkOrphanCheckpoints(projectRoot) {
+  const issues = [];
+  const stateDir = path.join(projectRoot, STATE_SUBPATH);
+  const cpDir = path.join(stateDir, 'checkpoints');
+  if (!fs.existsSync(cpDir)) return issues;
+  let entries;
+  try { entries = fs.readdirSync(cpDir); } catch { return issues; }
+
+  let currentTask = null;
+  try {
+    const statePath = path.join(stateDir, 'STATE.md');
+    if (fs.existsSync(statePath)) {
+      const { readState } = require('../../lib/state.cjs');
+      const s = readState(projectRoot);
+      currentTask = (s && s.frontmatter && s.frontmatter.current_task) || null;
+    }
+  } catch { /* state unreadable — treat as null current_task */ }
+
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    const taskId = name.slice(0, -5);
+    const cpPath = path.join(cpDir, name);
+    let cp;
+    try { cp = JSON.parse(fs.readFileSync(cpPath, 'utf-8')); }
+    catch { continue; }
+    if (!cp || cp.status !== 'in-progress') continue;
+    if (currentTask === taskId) continue;
+    issues.push({
+      id: 'orphan-checkpoint',
+      severity: 'warn',
+      fixable: 'manual',
+      details: {
+        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.',
+      },
+    });
+  }
+  return issues;
+}
+
 function _checkOutputSchemas(projectRoot) {
   const issues = [];
   const milestonesRoot = path.join(projectRoot, STATE_SUBPATH, 'milestones');
@@ -551,6 +610,7 @@ function _audit(projectRoot) {
   issues.push(..._checkNubosloopKnowledgeStore(projectRoot));
   issues.push(..._checkNubosloopConfig(projectRoot));
   issues.push(..._checkOrphanTmpFiles(projectRoot));
+  issues.push(..._checkOrphanCheckpoints(projectRoot));
   issues.push(..._checkOutputSchemas(projectRoot));
   return { issues, _codexContent: codex.content };
 }

package/bin/np-tools/doctor.test.cjs

@@ -169,6 +169,20 @@ test('DOC-8: flags nubosloop-knowledge-adapter-invalid for unsupported adapter',
   assert.ok(ids.includes('nubosloop-knowledge-adapter-invalid'));
 });
 
+test('DOC-9b: flags config-json-corrupt when config.json is unparseable', async () => {
+  const root = makeSandbox();
+  fs.writeFileSync(path.join(root, 'src.js'), 'export function a(){}');
+  scanCodebase.run([], { cwd: root, stdout: captureStdout().stub });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'config.json'), '{ not json');
+  const cap = captureStdout();
+  await doctor.run([], { cwd: root, stdout: cap.stub, stderr: cap.stub, askUser: async () => ({ value: false }) });
+  const out = cap.json();
+  const issue = out.issues.find((i) => i.id === 'config-json-corrupt');
+  assert.ok(issue, 'expected config-json-corrupt issue');
+  assert.equal(issue.severity, 'error');
+  assert.match(issue.details.hint, /Repair or delete/);
+});
+
 test('DOC-9: flags nubosloop-maxRounds-out-of-range when value > 10', async () => {
   const root = makeSandbox();
   fs.writeFileSync(path.join(root, 'src.js'), 'export function a(){}');

package/bin/np-tools/execute-milestone.cjs

@@ -2,22 +2,18 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const os = require('node:os');
-const crypto = require('node:crypto');
 
 const {
   NubosPilotError,
-  projectStateDir,
   atomicWriteFileSync,
 } = require('../../lib/core.cjs');
+const { emitInitPayload } = require('../../lib/init-emit.cjs');
 const layout = require('../../lib/layout.cjs');
 const { getPhase } = require('../../lib/roadmap.cjs');
 const { extractFrontmatter } = require('../../lib/frontmatter.cjs');
 const { getAgentSkills } = require('../../lib/agents.cjs');
 const textMode = require('../../lib/text-mode.cjs');
 
-const INLINE_THRESHOLD_BYTES = 16 * 1024;
-
 function _hasVerifyWorkFlag(list) {
   return Array.isArray(list) && list.some((a) => a === '--verify-work');
 }
@@ -45,23 +41,6 @@ function _safeSkills(name, cwd) {
   try { return getAgentSkills(name, cwd); } catch { return []; }
 }
 
-function _emit(payload, stdout, cwd) {
-  const json = JSON.stringify(payload, null, 2);
-  if (Buffer.byteLength(json, 'utf-8') <= INLINE_THRESHOLD_BYTES) {
-    stdout.write(json);
-    return;
-  }
-  let tmpDir;
-  try {
-    tmpDir = path.join(projectStateDir(cwd), '.tmp');
-    fs.mkdirSync(tmpDir, { recursive: true });
-  } catch { tmpDir = os.tmpdir(); }
-  const suffix = process.pid + '-' + crypto.randomBytes(4).toString('hex');
-  const tmpPath = path.join(tmpDir, 'init-execute-milestone-' + suffix + '.json');
-  fs.writeFileSync(tmpPath, json, 'utf-8');
-  stdout.write('@file:' + tmpPath);
-}
-
 function _readTaskPayload(taskPlanPath) {
   const raw = fs.readFileSync(taskPlanPath, 'utf-8');
   const { frontmatter, body } = extractFrontmatter(raw);
@@ -288,7 +267,7 @@ function run(args, ctx) {
       const mNum = _validateMilestoneArg(list[1]);
       const autoVerify = _hasVerifyWorkFlag(list.slice(2));
       const payload = _initPayload(mNum, cwd, { auto_verify: autoVerify });
-      _emit(payload, stdout, cwd);
+      emitInitPayload(payload, stdout, cwd, 'execute-milestone');
       return payload;
     }
     case 'execute-task': {
@@ -302,20 +281,20 @@ function run(args, ctx) {
         );
       }
       const payload = _findTaskByFullId(mNum, taskId, cwd);
-      _emit(payload, stdout, cwd);
+      emitInitPayload(payload, stdout, cwd, 'execute-milestone');
       return payload;
     }
     case 'finalize-slice': {
       const mNum = _validateMilestoneArg(list[1]);
       const sNum = _validateMilestoneArg(list[2]);
       const payload = _finalizeSlice(mNum, sNum, cwd);
-      _emit(payload, stdout, cwd);
+      emitInitPayload(payload, stdout, cwd, 'execute-milestone');
       return payload;
     }
     case 'finalize-milestone': {
       const mNum = _validateMilestoneArg(list[1]);
       const payload = _finalizeMilestone(mNum, cwd);
-      _emit(payload, stdout, cwd);
+      emitInitPayload(payload, stdout, cwd, 'execute-milestone');
       return payload;
     }
     default:
@@ -327,4 +306,4 @@ function run(args, ctx) {
   }
 }
 
-module.exports = { run, INLINE_THRESHOLD_BYTES };
+module.exports = { run };

package/bin/np-tools/handoff-write.cjs

@@ -1,8 +1,9 @@
 'use strict';
 
 const fs = require('node:fs');
-const { NubosPilotError } = require('../../lib/core.cjs');
+const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
 const { writeHandoff } = require('../../lib/handoff.cjs');
+const safePath = require('../../lib/safe-path.cjs');
 
 function _parseArgs(args) {
   const out = {
@@ -32,7 +33,20 @@ function run(args, opts) {
 
   let body = parsed.body || '';
   if (parsed.bodyFile) {
-    try { body = fs.readFileSync(parsed.bodyFile, 'utf-8'); }
+    let resolved;
+    try {
+      resolved = safePath.assertInsideAnyOf([cwd, projectStateDir(cwd)], parsed.bodyFile, 'body-file');
+    } catch (err) {
+      if (err && (err.code === 'safe-path-outside-base' || err.code === 'safe-path-invalid-input' || err.code === 'safe-path-base-missing')) {
+        throw new NubosPilotError(
+          'handoff-body-file-not-allowed',
+          '--body-file must reside inside the project or .nubos-pilot/: ' + parsed.bodyFile,
+          { path: parsed.bodyFile, cause: err.code },
+        );
+      }
+      throw err;
+    }
+    try { body = fs.readFileSync(resolved, 'utf-8'); }
     catch (err) {
       throw new NubosPilotError(
         'handoff-body-file-read-failed',

package/bin/np-tools/init-dispatch.test.cjs

@@ -33,6 +33,27 @@ test('TD-1: topLevelCommands routes metrics/resolve-model/plan-diff and siblings
   }
 });
 
+test('TD-1b: verify-work is reachable as top-level command (not only via init)', () => {
+  const np = require('../../np-tools.cjs');
+  assert.ok(np.topLevelCommands['verify-work'], 'verify-work must be exposed at top level for agents/workflows');
+  assert.equal(typeof np.topLevelCommands['verify-work'].run, 'function');
+});
+
+test('TD-1c: every initWorkflow is also exposed top-level (registry-parity invariant)', () => {
+  const np = require('../../np-tools.cjs');
+  for (const key of Object.keys(np.initWorkflows)) {
+    assert.ok(
+      np.topLevelCommands[key],
+      'initWorkflow "' + key + '" missing from topLevelCommands — both registries must list every agent-callable verb',
+    );
+    assert.strictEqual(
+      np.topLevelCommands[key],
+      np.initWorkflows[key],
+      'topLevelCommands["' + key + '"] must be the SAME module as initWorkflows["' + key + '"]',
+    );
+  }
+});
+
 test('TD-2: initWorkflows exposes plan-milestone + execute-milestone entries', () => {
   const np = require('../../np-tools.cjs');
   assert.ok(np.initWorkflows && typeof np.initWorkflows === 'object');

package/bin/np-tools/knowledge-search.cjs

@@ -31,9 +31,6 @@ function run(args, ctx) {
   }
   const result = search(parsed.query, cwd, { limit: parsed.limit });
   stdout.write(JSON.stringify(result));
-  // When run inside a Nubosloop task (--task), record Rule 9 evidence so the
-  // tool-use audit can verify the search actually happened. Best-effort:
-  // ledger failure must never fail the search itself.
   if (parsed.task) {
     try {
       require('../../lib/nubosloop.cjs').recordSearchEvidence(parsed.task, parsed.query, cwd);

package/bin/np-tools/learning-list.cjs

@@ -13,14 +13,12 @@ function run(argv, ctx) {
 
   const adapter = knowledgeAdapter.getAdapter(cwd);
   const all = adapter.list();
-  // Sort by occurrence desc, last_seen desc — most-used first.
   const sorted = all.slice().sort((a, b) => {
     const oc = (b.occurrence || 0) - (a.occurrence || 0);
     if (oc !== 0) return oc;
     return String(b.last_seen || '').localeCompare(String(a.last_seen || ''));
   });
   const truncated = sorted.slice(0, cap);
-  // Strip the bulky tokens[] array from the listing — it's an internal cache.
   const projected = truncated.map((l) => {
     const { tokens, ...rest } = l;
     return rest;

package/bin/np-tools/learning-log.cjs

@@ -1,8 +1,7 @@
 'use strict';
 
 const { NubosPilotError } = require('../../lib/core.cjs');
-const { TASK_ID_RE } = require('../../lib/checkpoint.cjs');
-const { MILESTONE_ID_RE } = require('../../lib/learnings.cjs');
+const { TASK_ID_RE, MILESTONE_ID_RE } = require('../../lib/ids.cjs');
 const knowledgeAdapter = require('../../lib/knowledge-adapter.cjs');
 const { getFlag } = require('./_args.cjs');
 
@@ -52,11 +51,6 @@ function run(args, ctx) {
   const learnings = require('../../lib/learnings.cjs');
   const fingerprint = learnings._fingerprint(pattern);
   const adapter = knowledgeAdapter.getAdapter(cwd);
-  // R5/risk from fifth review: the prior pre-scan-then-write approach raced
-  // a concurrent writer that landed the same fingerprint between the scan
-  // and the log() call. We now derive `was_new` from the post-write
-  // occurrence: logLearning is locked, so occurrence === 1 is determinative
-  // — exactly one log() call inside the lock window made the entry new.
   const result = adapter.log({ pattern, outcome, task_id: taskId, milestone_id: milestoneId });
   let occurrence = 1;
   if (Array.isArray(result && result.learnings)) {

package/bin/np-tools/loop-audit-tool-use.cjs

@@ -4,8 +4,7 @@ const checkpoint = require('../../lib/checkpoint.cjs');
 const nubosloop = require('../../lib/nubosloop.cjs');
 const agentsLib = require('../../lib/agents.cjs');
 const args = require('./_args.cjs');
-
-const TASK_ID_RE = checkpoint.TASK_ID_RE;
+const { TASK_ID_RE } = require('../../lib/ids.cjs');
 
 function run(argv, ctx) {
   const context = ctx || {};
@@ -16,14 +15,12 @@ function run(argv, ctx) {
   args.assertMatch(taskId, TASK_ID_RE, 'loop-audit-invalid-task-id', 'taskId');
   const tail = list.slice(1);
 
-  // Read mode: just dump the audit log.
   if (tail.includes('--read')) {
     const log = nubosloop.readToolUseAudit(taskId, cwd) || [];
     stdout.write(JSON.stringify({ task_id: taskId, audit: log }) + '\n');
     return { task_id: taskId, audit: log };
   }
 
-  // Append mode: agent + tool_use_log.
   const agent = args.getFlag(tail, '--agent');
   if (!agent) {
     throw new (require('../../lib/core.cjs').NubosPilotError)(
@@ -43,15 +40,8 @@ function run(argv, ctx) {
     } catch (err) {
       if (!err) throw err;
       if (err.code === 'loop-audit-agent-is-module') throw err;
-      // Any other error (agent-not-found, agent-not-a-module) means the name
-      // is not a known module — fall through and accept the audit.
     }
   }
-  // --tool-use-log is required for AUDITED_AGENTS (Rule 9 enforcement reads
-  // the tool list to verify search-knowledge / match-existing-learning calls).
-  // For non-audited spawns (critics, plan-checker, etc.) the orchestrator may
-  // omit it — we still record the spawn for Layer-C audit-trail evidence with
-  // an empty log. Explicit empty-array is also accepted.
   const isAuditedAgent = nubosloop.AUDITED_AGENTS.includes(agent);
   let log;
   if (tail.includes('--tool-use-log')) {