nubos-pilot 0.6.2 → 0.6.3

package/agents/np-nyquist-auditor.md

@@ -45,7 +45,7 @@ Before auditing, load:
 <execution_flow>
 
 <step name="load_requirements">
-Filter `.planning/REQUIREMENTS.md` (or `.nubos-pilot/REQUIREMENTS.md` if present) to the phase's `requirements[]` list supplied in input.
+Filter `.nubos-pilot/REQUIREMENTS.md` to the phase's `requirements[]` list supplied in input.
 
 Also extract requirement-ID references from each slice's `S<NNN>-PLAN.md` and each task's `T<NNNN>-PLAN.md` frontmatter `requirements:` + `must_haves:` blocks — they often imply requirement coverage without explicit REQ-ID mapping; capture those as additional observation targets.
 

package/agents/np-sc-extractor.md

@@ -17,7 +17,7 @@ You do NOT interview the user. You do NOT edit code. You do NOT re-open scope de
 - `goal`: the milestone's goal string (from `roadmap.yaml`)
 - `requirements`: array of REQ-IDs in scope (from `roadmap.yaml`)
 - `context_path`: path to `<milestone_dir>/<milestone_id>-CONTEXT.md` (just written by the workflow)
-- `requirements_path`: path to `.nubos-pilot/REQUIREMENTS.md` (or `.planning/REQUIREMENTS.md`)
+- `requirements_path`: path to `.nubos-pilot/REQUIREMENTS.md`
 - `existing_success_criteria`: current `success_criteria[]` from roadmap.yaml (may be empty)
 </input>
 

package/bin/np-tools/_commands.cjs

@@ -51,9 +51,16 @@ const COMMANDS = [
   { name: 'detect-runtime',  category: 'Utility', description: 'Print detected runtime id (claude, codex, gemini, …) — reads config.json ∨ env ∨ default' },
   { name: 'template-path',   category: 'Utility', description: 'Print absolute path to a package-shipped template by name (e.g. VALIDATION, milestone/CONTEXT)' },
   { name: 'update-phase-meta', category: 'Planning', description: 'Update roadmap.yaml phase fields (name/goal/requirements/success_criteria) via JSON patch' },
+  { name: 'phase-meta',        category: 'Planning', description: 'Read roadmap.yaml phase fields as JSON (supports --field NAME and --length for arrays)' },
+  { name: 'state-dir',         category: 'Utility',  description: 'Print project-state directory (.nubos-pilot) or a validated subdir via --subdir NAME' },
+  { name: 'render-template',   category: 'Utility',  description: 'Render a shipped template by name with --vars JSON (or --vars-file PATH)' },
+  { name: 'thread-resume',     category: 'Utility',  description: 'Bump a thread markdown on resume (status OPEN→IN_PROGRESS, refresh last_resumed) via atomic write' },
+  { name: 'state-incr',        category: 'Capture',  description: 'Increment a whitelisted STATE.md counter (e.g. pending_todos) under withFileLock' },
 
   { name: 'thread',           category: 'Utility', description: 'Cross-session thread CRUD (create/resume under .nubos-pilot/threads/)' },
-  { name: 'session-report',   category: 'Utility', description: 'Generate session report from metrics since .last-session pointer' },
+  { name: 'session-aggregate',     category: 'Utility', description: 'Aggregate session metrics under withFileLock; reads pointer .last-session unless --since overrides' },
+  { name: 'session-pointer-write', category: 'Utility', description: 'Atomic write of .nubos-pilot/reports/.last-session under withFileLock (ISO-8601 UTC)' },
+  { name: 'workspace-scan',        category: 'Install', description: 'Scan a workspace and emit inventory JSON (full result or --summary shape for /np:new-project)' },
   { name: 'cleanup',          category: 'Utility', description: 'Archive completed milestones to .nubos-pilot/archive/v<X.Y>/' },
 ];
 

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

@@ -0,0 +1,102 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const roadmap = require('../../lib/roadmap.cjs');
+
+const ALLOWED_FIELDS = new Set([
+  'number',
+  'id',
+  'name',
+  'goal',
+  'requirements',
+  'success_criteria',
+  'depends_on',
+  'status',
+]);
+
+function _parseArgs(args) {
+  const out = { milestone: null, field: null, length: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('-')) {
+      if (out.milestone == null) out.milestone = a;
+      continue;
+    }
+    if (a === '--field' || a === '-f') { out.field = args[++i] || null; continue; }
+    if (a === '--length' || a === '-l') { out.length = true; continue; }
+  }
+  return out;
+}
+
+function _validateMilestone(raw) {
+  if (raw == null) {
+    throw new NubosPilotError('phase-meta-missing-milestone',
+      'milestone number required (e.g. M002 or 2)', {});
+  }
+  const s = String(raw).trim();
+  const m = s.match(/^M?(\d+(?:\.\d+)?)$/i);
+  if (!m) {
+    throw new NubosPilotError('phase-meta-invalid-milestone',
+      'milestone must be M<NNN> or <number>', { milestone: raw });
+  }
+  return m[1];
+}
+
+function _project(phase) {
+  return {
+    number: phase.number,
+    id: phase.id || null,
+    name: phase.name || '',
+    goal: phase.goal || '',
+    requirements: Array.isArray(phase.requirements) ? phase.requirements : [],
+    success_criteria: Array.isArray(phase.success_criteria) ? phase.success_criteria : [],
+    depends_on: phase.depends_on || null,
+    status: phase.status || null,
+  };
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(args || []);
+  const mNum = _validateMilestone(parsed.milestone);
+
+  let def;
+  try {
+    def = roadmap.getPhase(mNum, cwd);
+  } catch (err) {
+    if (err && err.code === 'phase-not-found') {
+      throw new NubosPilotError('phase-meta-not-found',
+        'Milestone ' + mNum + ' not found in roadmap.yaml', { milestone: mNum });
+    }
+    throw err;
+  }
+
+  const projected = _project(def);
+
+  if (parsed.field) {
+    if (!ALLOWED_FIELDS.has(parsed.field)) {
+      throw new NubosPilotError('phase-meta-unknown-field',
+        'unknown field: ' + parsed.field,
+        { field: parsed.field, allowed: Array.from(ALLOWED_FIELDS) });
+    }
+    const value = projected[parsed.field];
+    if (parsed.length) {
+      if (!Array.isArray(value)) {
+        throw new NubosPilotError('phase-meta-length-non-array',
+          '--length requires an array field; ' + parsed.field + ' is not an array',
+          { field: parsed.field });
+      }
+      stdout.write(String(value.length));
+      return 0;
+    }
+    stdout.write(JSON.stringify(value));
+    return 0;
+  }
+
+  stdout.write(JSON.stringify(projected));
+  return 0;
+}
+
+module.exports = { run, _parseArgs, _validateMilestone, ALLOWED_FIELDS };

package/bin/np-tools/phase-meta.test.cjs

@@ -0,0 +1,134 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const mod = require('./phase-meta.cjs');
+
+const SEED = [
+  'schema_version: 1',
+  'milestones:',
+  '  - id: M001',
+  '    number: 1',
+  '    name: First',
+  '    goal: hello',
+  '    status: pending',
+  '    requirements: [UTIL-01, UTIL-02]',
+  '    success_criteria:',
+  '      - {id: SC-1, text: logs in}',
+  '      - {id: SC-2, text: logs out}',
+  '    slices: []',
+  '',
+].join('\n');
+
+function mkSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-pm-'));
+  fs.mkdirSync(path.join(dir, '.nubos-pilot'));
+  fs.writeFileSync(path.join(dir, '.nubos-pilot', 'roadmap.yaml'), SEED);
+  return dir;
+}
+
+function captureStdout() {
+  const chunks = [];
+  return {
+    stream: { write: (c) => { chunks.push(c); } },
+    read: () => chunks.join(''),
+  };
+}
+
+test('PM-1: _validateMilestone accepts M002, 2, and 2.1', () => {
+  assert.equal(mod._validateMilestone('M002'), '002');
+  assert.equal(mod._validateMilestone('2'), '2');
+  assert.equal(mod._validateMilestone('2.1'), '2.1');
+});
+
+test('PM-2: _validateMilestone rejects garbage', () => {
+  assert.throws(
+    () => mod._validateMilestone('bogus'),
+    (err) => err.code === 'phase-meta-invalid-milestone',
+  );
+});
+
+test('PM-3: run() without --field emits full projected JSON', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    const rc = mod.run(['1'], { cwd: dir, stdout: cap.stream });
+    assert.equal(rc, 0);
+    const out = JSON.parse(cap.read());
+    assert.equal(out.name, 'First');
+    assert.equal(out.goal, 'hello');
+    assert.deepEqual(out.requirements, ['UTIL-01', 'UTIL-02']);
+    assert.equal(out.success_criteria.length, 2);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('PM-4: --field success_criteria emits just that array as JSON', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    const rc = mod.run(['1', '--field', 'success_criteria'], { cwd: dir, stdout: cap.stream });
+    assert.equal(rc, 0);
+    const arr = JSON.parse(cap.read());
+    assert.equal(arr.length, 2);
+    assert.equal(arr[0].id, 'SC-1');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('PM-5: --field success_criteria --length emits count', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    const rc = mod.run(['1', '--field', 'success_criteria', '--length'], { cwd: dir, stdout: cap.stream });
+    assert.equal(rc, 0);
+    assert.equal(cap.read(), '2');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('PM-6: --length on non-array field throws', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    assert.throws(
+      () => mod.run(['1', '--field', 'name', '--length'], { cwd: dir, stdout: cap.stream }),
+      (err) => err.code === 'phase-meta-length-non-array',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('PM-7: unknown field throws', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    assert.throws(
+      () => mod.run(['1', '--field', 'bogus'], { cwd: dir, stdout: cap.stream }),
+      (err) => err.code === 'phase-meta-unknown-field',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('PM-8: missing milestone in roadmap throws phase-meta-not-found', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    assert.throws(
+      () => mod.run(['99'], { cwd: dir, stdout: cap.stream }),
+      (err) => err.code === 'phase-meta-not-found',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/bin/np-tools/render-template.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { loadTemplate } = require('../../lib/template.cjs');
+
+function _parseArgs(args) {
+  const out = { name: null, varsJson: null, varsFile: null };
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('-')) { rest.push(a); continue; }
+    if (a === '--vars' || a === '-v') { out.varsJson = args[++i] || null; continue; }
+    if (a === '--vars-file' || a === '-V') { out.varsFile = args[++i] || null; continue; }
+  }
+  if (rest.length) out.name = rest[0];
+  return out;
+}
+
+function _readVars(parsed) {
+  let raw = parsed.varsJson;
+  if (!raw && parsed.varsFile) {
+    const fs = require('node:fs');
+    raw = fs.readFileSync(parsed.varsFile, 'utf-8');
+  }
+  if (!raw) {
+    throw new NubosPilotError('render-template-missing-vars',
+      'vars JSON required (via --vars or --vars-file)', {});
+  }
+  try {
+    const obj = JSON.parse(raw);
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+      throw new Error('vars must be a JSON object');
+    }
+    return obj;
+  } catch (err) {
+    throw new NubosPilotError('render-template-invalid-vars',
+      'invalid vars JSON: ' + err.message, { cause: err.message });
+  }
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(args || []);
+  if (!parsed.name) {
+    throw new NubosPilotError('render-template-missing-name',
+      'template name required (e.g. milestone/CONTEXT)', {});
+  }
+  const vars = _readVars(parsed);
+  const rendered = loadTemplate(parsed.name, vars, cwd);
+  stdout.write(rendered);
+  return 0;
+}
+
+module.exports = { run, _parseArgs, _readVars };

package/bin/np-tools/render-template.test.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const mod = require('./render-template.cjs');
+
+function mkSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-rt-'));
+  fs.mkdirSync(path.join(dir, '.nubos-pilot'));
+  const tplDir = path.join(dir, '.nubos-pilot', 'templates', 'milestone');
+  fs.mkdirSync(tplDir, { recursive: true });
+  fs.writeFileSync(path.join(tplDir, 'CONTEXT.md'), '# {{title}}\n\nGoal: {{goal}}\n');
+  return dir;
+}
+
+function captureStdout() {
+  const chunks = [];
+  return {
+    stream: { write: (c) => { chunks.push(c); } },
+    read: () => chunks.join(''),
+  };
+}
+
+test('RT-1: renders template with --vars', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    const rc = mod.run([
+      'milestone/CONTEXT',
+      '--vars', JSON.stringify({ title: 'Auth', goal: 'Log in works' }),
+    ], { cwd: dir, stdout: cap.stream });
+    assert.equal(rc, 0);
+    assert.equal(cap.read(), '# Auth\n\nGoal: Log in works\n');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('RT-2: --vars-file also works', () => {
+  const dir = mkSandbox();
+  try {
+    const varsPath = path.join(dir, 'vars.json');
+    fs.writeFileSync(varsPath, JSON.stringify({ title: 'X', goal: 'Y' }));
+    const cap = captureStdout();
+    const rc = mod.run([
+      'milestone/CONTEXT',
+      '--vars-file', varsPath,
+    ], { cwd: dir, stdout: cap.stream });
+    assert.equal(rc, 0);
+    assert.equal(cap.read(), '# X\n\nGoal: Y\n');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('RT-3: missing name throws', () => {
+  assert.throws(
+    () => mod.run(['--vars', '{}'], { cwd: '/tmp', stdout: { write: () => {} } }),
+    (err) => err.code === 'render-template-missing-name',
+  );
+});
+
+test('RT-4: missing vars throws', () => {
+  const dir = mkSandbox();
+  try {
+    assert.throws(
+      () => mod.run(['milestone/CONTEXT'], { cwd: dir, stdout: { write: () => {} } }),
+      (err) => err.code === 'render-template-missing-vars',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('RT-5: invalid JSON vars throws', () => {
+  const dir = mkSandbox();
+  try {
+    assert.throws(
+      () => mod.run(['milestone/CONTEXT', '--vars', '{broken'], { cwd: dir, stdout: { write: () => {} } }),
+      (err) => err.code === 'render-template-invalid-vars',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('RT-6: non-object vars (array) rejected', () => {
+  const dir = mkSandbox();
+  try {
+    assert.throws(
+      () => mod.run(['milestone/CONTEXT', '--vars', '[]'], { cwd: dir, stdout: { write: () => {} } }),
+      (err) => err.code === 'render-template-invalid-vars',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('RT-7: missing placeholder in vars throws template-unresolved-var', () => {
+  const dir = mkSandbox();
+  try {
+    assert.throws(
+      () => mod.run(['milestone/CONTEXT', '--vars', '{"title":"X"}'], { cwd: dir, stdout: { write: () => {} } }),
+      (err) => err.code === 'template-unresolved-var',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

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

@@ -8,6 +8,7 @@ const crypto = require('node:crypto');
 const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
 const layout = require('../../lib/layout.cjs');
 const textMode = require('../../lib/text-mode.cjs');
+const { DEFAULT_RESEARCH_TOOLS } = require('../../lib/config-defaults.cjs');
 
 const INLINE_THRESHOLD_BYTES = 16 * 1024;
 
@@ -46,10 +47,31 @@ function _readMilestoneDef(cwd, mNum) {
   }
 }
 
-function _toolsAvailable() {
+function _readConfigResearchTools(cwd) {
+  try {
+    const configPath = path.join(projectStateDir(cwd), 'config.json');
+    if (!fs.existsSync(configPath)) return {};
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const wf = parsed && parsed.workflow;
+    const rt = wf && wf.research_tools;
+    return rt && typeof rt === 'object' ? rt : {};
+  } catch (_err) {
+    return {};
+  }
+}
+
+function _resolveToolFlag(envValue, configValue, defaultValue) {
+  if (envValue === '1' || envValue === 'true') return true;
+  if (envValue === '0' || envValue === 'false') return false;
+  if (typeof configValue === 'boolean') return configValue;
+  return defaultValue;
+}
+
+function _toolsAvailable(cwd) {
+  const cfg = _readConfigResearchTools(cwd);
   return {
-    WebFetch: process.env.NP_TOOLS_WEBFETCH === '1',
-    Context7: process.env.NP_TOOLS_CONTEXT7 === '1',
+    WebFetch: _resolveToolFlag(process.env.NP_TOOLS_WEBFETCH, cfg.WebFetch, DEFAULT_RESEARCH_TOOLS.WebFetch),
+    Context7: _resolveToolFlag(process.env.NP_TOOLS_CONTEXT7, cfg.Context7, DEFAULT_RESEARCH_TOOLS.Context7),
   };
 }
 
@@ -120,7 +142,7 @@ function run(args, ctx) {
     requirements: Array.isArray(def.requirements) ? def.requirements.slice() : [],
     has_research,
     slice_research: sliceResearch,
-    tools_available: _toolsAvailable(),
+    tools_available: _toolsAvailable(cwd),
     text_mode: tmDetail.enabled,
     text_mode_source: tmDetail.source,
     agent_skills: _agentSkills(cwd),
@@ -129,4 +151,4 @@ function run(args, ctx) {
   return payload;
 }
 
-module.exports = { run, INLINE_THRESHOLD_BYTES, _parseMilestoneArg };
+module.exports = { run, INLINE_THRESHOLD_BYTES, _parseMilestoneArg, _toolsAvailable, _resolveToolFlag };

package/bin/np-tools/research-phase.test.cjs

@@ -82,18 +82,18 @@ test('RP-2: has_research=true iff {milestone_dir}/{milestone_id}-RESEARCH.md exi
   assert.equal(payload.has_research, true);
 });
 
-test('RP-3: tools_available defaults to {false,false} when env vars absent', () => {
+test('RP-3: tools_available defaults to {true,true} when env vars + config absent (optimistic default)', () => {
   const sandbox = makeSandbox();
   seedRoadmapYaml(sandbox, _baseRoadmap());
   _clearEnv();
   const cap = _captureStdout();
   subcmd.run(['5'], { cwd: sandbox, stdout: cap.stub });
   const payload = JSON.parse(cap.get().trim());
-  assert.equal(payload.tools_available.WebFetch, false);
-  assert.equal(payload.tools_available.Context7, false);
+  assert.equal(payload.tools_available.WebFetch, true);
+  assert.equal(payload.tools_available.Context7, true);
 });
 
-test('RP-4: NP_TOOLS_WEBFETCH=1 and NP_TOOLS_CONTEXT7=1 flip both booleans', () => {
+test('RP-4: NP_TOOLS_WEBFETCH=1 and NP_TOOLS_CONTEXT7=1 keep both true', () => {
   const sandbox = makeSandbox();
   seedRoadmapYaml(sandbox, _baseRoadmap());
   process.env.NP_TOOLS_WEBFETCH = '1';
@@ -105,6 +105,55 @@ test('RP-4: NP_TOOLS_WEBFETCH=1 and NP_TOOLS_CONTEXT7=1 flip both booleans', ()
   assert.equal(payload.tools_available.Context7, true);
 });
 
+test('RP-4b: NP_TOOLS_WEBFETCH=0 and NP_TOOLS_CONTEXT7=0 flip both booleans to false', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  process.env.NP_TOOLS_WEBFETCH = '0';
+  process.env.NP_TOOLS_CONTEXT7 = '0';
+  const cap = _captureStdout();
+  subcmd.run(['5'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.tools_available.WebFetch, false);
+  assert.equal(payload.tools_available.Context7, false);
+});
+
+test('RP-4c: config.workflow.research_tools overrides default when env absent', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const configPath = path.join(sandbox, '.nubos-pilot', 'config.json');
+  fs.writeFileSync(configPath, JSON.stringify({
+    workflow: { research_tools: { WebFetch: false, Context7: true } },
+  }));
+  _clearEnv();
+  const cap = _captureStdout();
+  subcmd.run(['5'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.tools_available.WebFetch, false);
+  assert.equal(payload.tools_available.Context7, true);
+});
+
+test('RP-4d: env var wins over config (env=1 overrides config=false)', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const configPath = path.join(sandbox, '.nubos-pilot', 'config.json');
+  fs.writeFileSync(configPath, JSON.stringify({
+    workflow: { research_tools: { WebFetch: false, Context7: false } },
+  }));
+  process.env.NP_TOOLS_WEBFETCH = '1';
+  const cap = _captureStdout();
+  subcmd.run(['5'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.tools_available.WebFetch, true);
+  assert.equal(payload.tools_available.Context7, false);
+});
+
+test('RP-4e: _resolveToolFlag: "true"/"false" strings handled', () => {
+  assert.equal(subcmd._resolveToolFlag('true', false, false), true);
+  assert.equal(subcmd._resolveToolFlag('false', true, true), false);
+  assert.equal(subcmd._resolveToolFlag(undefined, undefined, true), true);
+  assert.equal(subcmd._resolveToolFlag(undefined, false, true), false);
+});
+
 test('RP-5: missing phase number throws research-phase-not-found', () => {
   const sandbox = makeSandbox();
   seedRoadmapYaml(sandbox, _baseRoadmap());

package/bin/np-tools/session-aggregate.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  NubosPilotError,
+  projectStateDir,
+  withFileLock,
+} = require('../../lib/core.cjs');
+const { aggregateSession } = require('../../lib/metrics-aggregate.cjs');
+
+const LOCK_TIMEOUT_MS = 10000;
+
+function _parseArgs(args) {
+  const out = { since: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--since' || a === '-s') { out.since = args[++i] || null; continue; }
+  }
+  return out;
+}
+
+function _pointerPath(cwd) {
+  return path.join(projectStateDir(cwd), 'reports', '.last-session');
+}
+
+async function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(args || []);
+
+  const pointer = _pointerPath(cwd);
+  fs.mkdirSync(path.dirname(pointer), { recursive: true });
+
+  let summary;
+  try {
+    summary = await withFileLock(pointer, async () => {
+      let since = parsed.since || '';
+      if (!since && fs.existsSync(pointer)) {
+        since = fs.readFileSync(pointer, 'utf-8').trim();
+      }
+      return aggregateSession(since || null, { cwd });
+    }, { timeoutMs: LOCK_TIMEOUT_MS });
+  } catch (err) {
+    if (err && err.name === 'NubosPilotError') throw err;
+    throw new NubosPilotError('session-aggregate-failed',
+      'aggregate failed: ' + (err && err.message),
+      { cause: err && err.message });
+  }
+
+  stdout.write(JSON.stringify(summary));
+  return 0;
+}
+
+module.exports = { run, _parseArgs, _pointerPath, LOCK_TIMEOUT_MS };