nubos-pilot 0.7.0 → 0.7.2

package/agents/np-executor.md

@@ -112,6 +112,38 @@ into the `task(…)` commit. If `workflow.commit_docs=true`, the
 - Auto-discover files via `git status` — the plan declares scope, not the filesystem.
 </scope_guardrail>
 
+## Handoff Protocol
+
+Agent handoffs are persistent notes between phase invocations — context that doesn't belong in commit messages or frontmatter. They survive across spawns and let downstream agents see non-obvious signals you discovered during execution.
+
+**At start, check handoffs addressed to you:**
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs handoff-list --for np-executor --milestone M<NNN> --status open
+```
+
+For each relevant entry:
+1. `node .nubos-pilot/bin/np-tools.cjs handoff-read <id>` — read body
+2. Apply the context to your work
+3. `node .nubos-pilot/bin/np-tools.cjs handoff-status <id> acted`
+
+**At end, write a handoff ONLY for genuine cross-phase signals:**
+
+- Non-obvious compromise the verifier must know about → `--to np-verifier`
+- Plan flaw the next planner run should address → `--to np-planner`
+- Trap in shared code that applies broadly → `--to "*"` (broadcast)
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs handoff-write \
+  --from np-executor \
+  --to np-verifier \
+  --topic "Short subject" \
+  --milestone M<NNN> --slice M<NNN>-S<NNN> --task M<NNN>-S<NNN>-T<NNNN> \
+  --body "What downstream needs to know"
+```
+
+Do NOT write handoffs for routine work. One handoff per genuine signal; noise trains future agents to ignore the channel.
+
 ## Stop Conditions
 
 Hard-stop (report to orchestrator, do not attempt recovery):

package/agents/np-planner.md

@@ -14,6 +14,34 @@ Spawned by:
 - `/np:plan-phase <N> --gaps` — gap closure from verification failures
 - `/np:plan-phase <N>` in revision mode — updating plans based on plan-checker feedback
 
+## Handoff Protocol
+
+Agent handoffs are persistent notes between phase invocations. Before planning, check handoffs addressed to `np-planner` for this milestone:
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs handoff-list --for np-planner --milestone M<NNN> --status open
+```
+
+For each entry:
+1. `node .nubos-pilot/bin/np-tools.cjs handoff-read <id>` — read body
+2. Integrate the signal into your plan, OR reject it with a return handoff explaining why (executors often flag plan-flaws this way; honor them or refute them — never silently ignore).
+3. `node .nubos-pilot/bin/np-tools.cjs handoff-status <id> acted`
+
+**Write a handoff ONLY for cross-phase signals downstream needs:**
+
+- Scope nuance that doesn't fit cleanly in the slice `PLAN.md` → `--to np-executor`
+- SC interpretation that matters at verification time → `--to np-verifier`
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs handoff-write \
+  --from np-planner --to <target> \
+  --topic "Short subject" \
+  --milestone M<NNN> \
+  --body "What downstream needs to know"
+```
+
+Do NOT write handoffs for information already captured in PLAN/ROADMAP/CONTEXT.
+
 ## Layout (MANDATORY)
 
 Every artifact you write MUST land at exactly these paths. The orchestrator provides the absolute paths in the `<files_to_write>` block — use them verbatim.

package/agents/np-researcher.md

@@ -24,6 +24,34 @@ anchor points for your research — do not propose replacements without
 explicit justification. If `INDEX.md` is absent, report and stop —
 `np:scan-codebase` must run first.
 
+## Handoff Protocol
+
+Agent handoffs are persistent notes between phase invocations. Before researching, check handoffs addressed to `np-researcher`:
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs handoff-list --for np-researcher --milestone M<NNN> --status open
+```
+
+For each entry:
+1. `node .nubos-pilot/bin/np-tools.cjs handoff-read <id>` — read body
+2. Let the signal shape your research focus (e.g. a verifier-flagged uncertain SC steers deeper investigation in that area)
+3. `node .nubos-pilot/bin/np-tools.cjs handoff-status <id> acted`
+
+**Write a handoff when findings apply beyond this single RESEARCH.md:**
+
+- Evidence hint for a known-hard SC → `--to np-verifier`
+- Cross-milestone trap future planners must see → `--to np-planner` without `--milestone` (global scope)
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs handoff-write \
+  --from np-researcher --to <target> \
+  --topic "Short subject" \
+  [--milestone M<NNN>] \
+  --body "What downstream needs to know"
+```
+
+Do NOT use handoffs as a replacement for RESEARCH.md content — they are for signals that transcend this milestone's research doc.
+
 ## Tool Availability Detection
 
 On startup, before doing any research work, probe the web + MCP surface:

package/agents/np-verifier.md

@@ -32,6 +32,21 @@ The orchestrator provides these in your prompt context. Read every path it hands
 | success_criteria (from init payload) | The list of SC strings to classify. | provided inline in prompt |
 | Task commits | `git log --grep='^task(M<NNN>-'` → audit trail. | git history |
 
+## Handoff Protocol (read-only)
+
+Agent handoffs are persistent notes between phase invocations. Before classifying, check handoffs addressed to `np-verifier` for this milestone:
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs handoff-list --for np-verifier --milestone M<NNN> --status open
+```
+
+For each entry:
+1. `node .nubos-pilot/bin/np-tools.cjs handoff-read <id>` — read body
+2. Fold the context into your evidence gathering (executors often flag compromises that would otherwise read as `Fail` — the handoff explains the compromise and may move the SC to `Pass` or `Defer`).
+3. `node .nubos-pilot/bin/np-tools.cjs handoff-status <id> acted`
+
+**You do NOT write handoffs.** Verifier is detection-only — your findings land in `VERIFICATION.md`, never in the handoff channel. If you have no Write tool, writing handoffs is impossible anyway.
+
 ## Workflow
 
 1. **Parse success_criteria:** read the prompt-provided SC list (from `np-tools.cjs init verify-work <N>`).

package/bin/np-tools/_commands.cjs

@@ -54,6 +54,16 @@ const COMMANDS = [
   { 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: 'render-todo',       category: 'Utility',  description: 'Render slice TODO.md rollup (checkbox view of task statuses) for a slice full-id' },
+  { name: 'handoff-write',     category: 'Capture',  description: 'Write an agent-to-agent handoff note (milestone-scoped by default, global without --milestone)' },
+  { name: 'handoff-read',      category: 'Capture',  description: 'Read a single handoff by id (returns frontmatter + body as JSON)' },
+  { name: 'handoff-list',      category: 'Capture',  description: 'List handoffs (JSON array); filter with --for AGENT, --milestone M<NNN>, --status STATUS, --global' },
+  { name: 'handoff-status',    category: 'Capture',  description: 'Update a handoff status (open|read|acted|archived)' },
+  { name: 'worktree-create',   category: 'Execution', description: 'Create an isolated git worktree for a slice (branch np/<mid>-<sid> off current HEAD) under .nubos-pilot/worktrees/' },
+  { name: 'worktree-remove',   category: 'Execution', description: 'Remove a slice worktree + delete its branch (--force / --keep-branch)' },
+  { name: 'worktree-list',     category: 'Execution', description: 'List all nubos-pilot-managed slice worktrees (np/<mid>-<sid> only) as JSON' },
+  { name: 'worktree-ff-merge', category: 'Execution', description: 'Fast-forward merge a slice branch back to its base (fails hard on non-FF)' },
+  { name: 'dashboard',         category: 'Utility',   description: 'One-shot console dashboard of milestones, slices, and tasks. Read-only; flags: --json, --no-color' },
   { 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' },
 

package/bin/np-tools/dashboard.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+const { collectSnapshot, renderSnapshot } = require('../../lib/dashboard.cjs');
+
+function _parseArgs(args) {
+  const out = { json: false, noColor: false };
+  for (const a of args) {
+    if (a === '--json')     out.json = true;
+    else if (a === '--no-color') out.noColor = true;
+  }
+  return out;
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+
+  const snap = collectSnapshot(cwd);
+  if (parsed.json) {
+    stdout.write(JSON.stringify(snap, null, 2) + '\n');
+    return 0;
+  }
+  const useColor = !parsed.noColor && Boolean(stdout.isTTY);
+  stdout.write(renderSnapshot(snap, { color: useColor }) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/doctor.cjs

@@ -7,15 +7,45 @@ const path = require('node:path');
 const { NubosPilotError, atomicWriteFileSync } = require('../../lib/core.cjs');
 const manifestMod = require('../../lib/install/manifest.cjs');
 const codexTomlMod = require('../../lib/install/codex-toml.cjs');
+const runtimeAssetsMod = require('../../lib/install/runtime-assets.cjs');
 const askuserMod = require('../../lib/askuser.cjs');
 const codebaseManifest = require('../../lib/codebase-manifest.cjs');
 const { scan: workspaceScan } = require('../../lib/workspace-scan.cjs');
 
 const PAYLOAD_SUBPATH = path.join('.claude', 'nubos-pilot');
+const STATE_SUBPATH = '.nubos-pilot';
 const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
+const OPENCODE_LOCAL_PREFIX = '.opencode/nubos-pilot/';
+const OPENCODE_GLOBAL_PREFIX = '~/.config/opencode/nubos-pilot/';
 
-function _payloadDirFor(projectRoot) {
-  return path.join(projectRoot, PAYLOAD_SUBPATH);
+function _readScope(projectRoot) {
+  const cfgPath = path.join(projectRoot, STATE_SUBPATH, 'config.json');
+  if (!fs.existsSync(cfgPath)) return 'local';
+  try {
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    return cfg && cfg.scope === 'global' ? 'global' : 'local';
+  } catch {
+    return 'local';
+  }
+}
+
+function _payloadBaseFor(projectRoot, scope) {
+  return scope === 'global' ? os.homedir() : projectRoot;
+}
+
+function _payloadDirFor(projectRoot, scope) {
+  return path.join(_payloadBaseFor(projectRoot, scope), PAYLOAD_SUBPATH);
+}
+
+function _resolveManifestEntry(rel, projectRoot, scope) {
+  if (rel.startsWith('~/')) {
+    return path.join(os.homedir(), rel.slice(2));
+  }
+  const base = _payloadBaseFor(projectRoot, scope);
+  if (runtimeAssetsMod.isAssetManifestKey(rel) || rel.startsWith(OPENCODE_LOCAL_PREFIX)) {
+    return path.join(base, rel);
+  }
+  return path.join(_payloadDirFor(projectRoot, scope), rel);
 }
 
 function _pkgVersion() {
@@ -26,8 +56,9 @@ function _pkgVersion() {
   }
 }
 
-function _checkManifestIntegrity(payloadDir) {
+function _checkManifestIntegrity(projectRoot, scope) {
   const issues = [];
+  const payloadDir = _payloadDirFor(projectRoot, scope);
   let manifest = null;
   try {
     manifest = manifestMod.readManifest(payloadDir);
@@ -51,7 +82,7 @@ function _checkManifestIntegrity(payloadDir) {
   }
   const files = (manifest.files && typeof manifest.files === 'object') ? manifest.files : {};
   for (const rel of Object.keys(files)) {
-    const full = path.join(payloadDir, rel);
+    const full = _resolveManifestEntry(rel, projectRoot, scope);
     if (!fs.existsSync(full)) {
       issues.push({
         id: 'payload-missing',
@@ -306,9 +337,10 @@ function _checkMilestoneLayout(projectRoot) {
 }
 
 function _audit(projectRoot) {
-  const payloadDir = _payloadDirFor(projectRoot);
+  const scope = _readScope(projectRoot);
+  const payloadDir = _payloadDirFor(projectRoot, scope);
   const issues = [];
-  const { manifest, issues: manifestIssues } = _checkManifestIntegrity(payloadDir);
+  const { manifest, issues: manifestIssues } = _checkManifestIntegrity(projectRoot, scope);
   issues.push(...manifestIssues);
   issues.push(..._checkVersionMismatch(manifest));
   issues.push(..._checkHooksMissing(manifest, payloadDir));

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

@@ -85,6 +85,35 @@ test('DOC-4: flags codebase-tbd-docs for modules with _TBD Purpose', async () =>
   assert.ok(tbd.details.count >= 1);
 });
 
+test('DOC-6: asset manifest keys resolve to project root, not payloadDir', async () => {
+  const root = makeSandbox();
+
+  const payloadDir = path.join(root, '.claude', 'nubos-pilot');
+  fs.mkdirSync(payloadDir, { recursive: true });
+  fs.writeFileSync(path.join(payloadDir, '.manifest.json'), JSON.stringify({
+    version: '0.0.0',
+    timestamp: new Date().toISOString(),
+    files: {
+      '.claude/commands/np/foo.md': 'deadbeef',
+      '.claude/agents/np-bar.md': 'deadbeef',
+    },
+  }));
+  const cmdDir = path.join(root, '.claude', 'commands', 'np');
+  const agentsDir = path.join(root, '.claude', 'agents');
+  fs.mkdirSync(cmdDir, { recursive: true });
+  fs.mkdirSync(agentsDir, { recursive: true });
+  fs.writeFileSync(path.join(cmdDir, 'foo.md'), 'x');
+  fs.writeFileSync(path.join(agentsDir, 'np-bar.md'), 'y');
+
+  const cap = captureStdout();
+  await doctor.run([], { cwd: root, stdout: cap.stub, stderr: cap.stub, askUser: async () => ({ value: false }) });
+  const out = cap.json();
+  const missing = out.issues.filter((i) => i.id === 'payload-missing');
+  assert.equal(missing.length, 0,
+    'asset keys must resolve to project-root paths (found ' +
+    missing.map((m) => m.file).join(', ') + ')');
+});
+
 test('DOC-5: no tbd flag after prose applied', async () => {
   const root = makeSandbox();
   fs.mkdirSync(path.join(root, 'src'), { recursive: true });

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

@@ -0,0 +1,27 @@
+'use strict';
+
+const { listHandoffs } = require('../../lib/handoff.cjs');
+
+function _parseArgs(args) {
+  const out = { for: null, milestone: null, status: null, global: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--for')        { out.for = args[++i] || null; continue; }
+    if (a === '--milestone')  { out.milestone = args[++i] || null; continue; }
+    if (a === '--status')     { out.status = args[++i] || null; continue; }
+    if (a === '--global')     { out.global = true; continue; }
+  }
+  return out;
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+  const list = listHandoffs(parsed, cwd);
+  stdout.write(JSON.stringify(list) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

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

@@ -0,0 +1,20 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { readHandoff } = require('../../lib/handoff.cjs');
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const id = list.find((a) => !a.startsWith('-'));
+  if (!id) {
+    throw new NubosPilotError('handoff-read-missing-id', 'handoff id required', {});
+  }
+  const rec = readHandoff(id, cwd);
+  stdout.write(JSON.stringify(rec) + '\n');
+  return 0;
+}
+
+module.exports = { run };

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

@@ -0,0 +1,26 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { setHandoffStatus } = require('../../lib/handoff.cjs');
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const positional = list.filter((a) => !a.startsWith('-'));
+  const id = positional[0];
+  const newStatus = positional[1];
+  if (!id || !newStatus) {
+    throw new NubosPilotError(
+      'handoff-status-missing-args',
+      'usage: handoff-status <id> <new-status>',
+      { got: { id, newStatus } },
+    );
+  }
+  const result = setHandoffStatus(id, newStatus, cwd);
+  stdout.write(JSON.stringify({ id, status: result }) + '\n');
+  return 0;
+}
+
+module.exports = { run };

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

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('node:fs');
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { writeHandoff } = require('../../lib/handoff.cjs');
+
+function _parseArgs(args) {
+  const out = {
+    from: null, to: null, topic: null,
+    milestone: null, slice: null, task: null,
+    body: null, bodyFile: null,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--from')       { out.from = args[++i] || null; continue; }
+    if (a === '--to')         { out.to = args[++i] || null; continue; }
+    if (a === '--topic')      { out.topic = args[++i] || null; continue; }
+    if (a === '--milestone')  { out.milestone = args[++i] || null; continue; }
+    if (a === '--slice')      { out.slice = args[++i] || null; continue; }
+    if (a === '--task')       { out.task = args[++i] || null; continue; }
+    if (a === '--body')       { out.body = args[++i] || null; continue; }
+    if (a === '--body-file')  { out.bodyFile = args[++i] || null; continue; }
+  }
+  return out;
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+
+  let body = parsed.body || '';
+  if (parsed.bodyFile) {
+    try { body = fs.readFileSync(parsed.bodyFile, 'utf-8'); }
+    catch (err) {
+      throw new NubosPilotError(
+        'handoff-body-file-read-failed',
+        'failed to read --body-file: ' + (err && err.message),
+        { path: parsed.bodyFile },
+      );
+    }
+  }
+
+  const result = writeHandoff({
+    from: parsed.from,
+    to: parsed.to,
+    topic: parsed.topic,
+    milestone: parsed.milestone,
+    slice: parsed.slice,
+    task: parsed.task,
+    body,
+  }, cwd);
+
+  stdout.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

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

@@ -357,6 +357,19 @@ function _scaffoldAllTasks(mNum, cwd) {
   for (const s of slices) {
     per.push(_scaffoldSliceTasks(mNum, s.number, cwd));
   }
+
+  const { renderTodoMd } = require('../../lib/todo.cjs');
+  const todos = [];
+  for (const s of slices) {
+    try {
+      todos.push(renderTodoMd(s.full_id, cwd));
+    } catch (err) {
+      process.stderr.write(
+        '[nubos-pilot warn] TODO.md render failed for ' + s.full_id + ': ' + ((err && err.message) || err) + '\n',
+      );
+    }
+  }
+
   const total = per.reduce((acc, p) => acc + (p.task_count || 0), 0);
   return {
     scaffolded: per,
@@ -364,6 +377,7 @@ function _scaffoldAllTasks(mNum, cwd) {
     milestone: layout.mId(mNum),
     total_tasks: total,
     normalized_ids: normalized.changed ? normalized.remap : {},
+    todos_rendered: todos,
   };
 }
 

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

@@ -0,0 +1,24 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { renderTodoMd } = require('../../lib/todo.cjs');
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const sliceFullId = list.find((a) => !a.startsWith('-'));
+  if (!sliceFullId) {
+    throw new NubosPilotError(
+      'render-todo-missing-slice',
+      'slice full-id required (e.g. M001-S001)',
+      {},
+    );
+  }
+  const target = renderTodoMd(sliceFullId, cwd);
+  stdout.write(target + '\n');
+  return 0;
+}
+
+module.exports = { run };

package/bin/np-tools/reset-slice.cjs

@@ -8,6 +8,11 @@ const { restoreFiles } = require('../../lib/git.cjs');
 const { deleteCheckpoint, listCheckpoints } = require('../../lib/checkpoint.cjs');
 const layout = require('../../lib/layout.cjs');
 const { extractFrontmatter } = require('../../lib/frontmatter.cjs');
+const {
+  hasSliceWorktree,
+  removeSliceWorktree,
+  worktreeIsolationEnabled,
+} = require('../../lib/worktree.cjs');
 
 function _resolveTaskId(explicit, cwd) {
   if (explicit) {
@@ -44,13 +49,33 @@ function _readTaskFiles(taskId, cwd) {
   return Array.isArray(frontmatter.files_modified) ? frontmatter.files_modified : [];
 }
 
+function _maybeRemoveWorktreeForTask(taskId, cwd) {
+  if (!worktreeIsolationEnabled(cwd)) return null;
+  let parsed;
+  try { parsed = layout.parseTaskFullId(taskId); } catch { return null; }
+  const sliceFullId = layout.sliceFullId(parsed.milestone, parsed.slice);
+  let exists = false;
+  try { exists = hasSliceWorktree(sliceFullId, cwd); } catch { exists = false; }
+  if (!exists) return null;
+  try {
+    return removeSliceWorktree(sliceFullId, cwd, { force: true });
+  } catch (err) {
+    process.stderr.write(
+      '[nubos-pilot warn] removeSliceWorktree failed for ' + sliceFullId + ': ' + ((err && err.message) || err) + '\n',
+    );
+    return null;
+  }
+}
+
 function run(args, ctx) {
   const context = ctx || {};
   const cwd = context.cwd || process.cwd();
   const stdout = context.stdout || process.stdout;
   const list = Array.isArray(args) ? args : [];
 
-  const explicit = list[0] && !list[0].startsWith('--') ? list[0] : null;
+  const keepWorktree = list.includes('--keep-worktree');
+  const positional = list.filter((a) => a && !a.startsWith('--'));
+  const explicit = positional[0] || null;
   const taskId = _resolveTaskId(explicit, cwd);
 
   if (!taskId) {
@@ -91,12 +116,16 @@ function run(args, ctx) {
     return { frontmatter: fm, body: state.body };
   }, cwd);
 
+  const worktreeRemoved = keepWorktree ? null : _maybeRemoveWorktreeForTask(taskId, cwd);
+
   const payload = {
     ok: true,
     task_id: taskId,
     restored_files: files,
     deleted_checkpoints: [taskId],
-    message: 'in-flight task discarded; working tree restored to HEAD',
+    worktree_removed: worktreeRemoved,
+    message: 'in-flight task discarded; working tree restored to HEAD'
+      + (worktreeRemoved ? '; worktree ' + worktreeRemoved.branch + ' removed' : ''),
   };
   stdout.write(JSON.stringify(payload));
   return payload;

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

@@ -5,6 +5,29 @@ const { readState } = require('../../lib/state.cjs');
 const { readCheckpoint, listCheckpoints } = require('../../lib/checkpoint.cjs');
 const { TASK_ID_RE } = require('../../lib/tasks.cjs');
 const textMode = require('../../lib/text-mode.cjs');
+const layout = require('../../lib/layout.cjs');
+const {
+  hasSliceWorktree,
+  sliceWorktreePath,
+  sliceBranchName,
+  worktreeIsolationEnabled,
+  listSliceWorktrees,
+} = require('../../lib/worktree.cjs');
+
+function _worktreeInfoForTask(taskId, cwd) {
+  if (!taskId || !worktreeIsolationEnabled(cwd)) return null;
+  let parsed;
+  try { parsed = layout.parseTaskFullId(taskId); } catch { return null; }
+  const sliceFullId = layout.sliceFullId(parsed.milestone, parsed.slice);
+  let exists = false;
+  try { exists = hasSliceWorktree(sliceFullId, cwd); } catch { exists = false; }
+  if (!exists) return null;
+  return {
+    slice_full_id: sliceFullId,
+    branch: sliceBranchName(sliceFullId),
+    path: sliceWorktreePath(sliceFullId, cwd),
+  };
+}
 
 function _safeReadState(cwd) {
   try { return readState(cwd); } catch { return null; }
@@ -74,6 +97,25 @@ function run(_args, ctx) {
   payload.text_mode = tmDetail.enabled;
   payload.text_mode_source = tmDetail.source;
 
+  const wtInfo = _worktreeInfoForTask(currentTask, cwd);
+  if (wtInfo) payload.worktree = wtInfo;
+  payload.worktree_isolation = worktreeIsolationEnabled(cwd);
+  let stale = [];
+  try {
+    stale = listSliceWorktrees(cwd).filter((w) => {
+      const b = w.branch;
+      const activeBranch = wtInfo && wtInfo.branch;
+      return b !== activeBranch;
+    });
+  } catch { stale = []; }
+  if (stale.length > 0) {
+    payload.stale_worktrees = stale.map((w) => ({
+      slice_full_id: w.slice_full_id,
+      branch: w.branch,
+      path: w.path,
+    }));
+  }
+
   stdout.write(JSON.stringify(payload));
   return payload;
 }

package/bin/np-tools/worktree-create.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { createSliceWorktree } = require('../../lib/worktree.cjs');
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const sliceFullId = list.find((a) => !a.startsWith('-'));
+  if (!sliceFullId) {
+    throw new NubosPilotError(
+      'worktree-create-missing-slice',
+      'slice full-id required (e.g. M001-S001)',
+      {},
+    );
+  }
+  const result = createSliceWorktree(sliceFullId, cwd);
+  stdout.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+module.exports = { run };

package/bin/np-tools/worktree-ff-merge.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { ffMergeSliceWorktree } = require('../../lib/worktree.cjs');
+
+function _parseArgs(args) {
+  const out = { sliceFullId: null, target: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--target') { out.target = args[++i] || null; continue; }
+    if (!a.startsWith('-') && !out.sliceFullId) out.sliceFullId = a;
+  }
+  return out;
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+  if (!parsed.sliceFullId) {
+    throw new NubosPilotError(
+      'worktree-ff-merge-missing-slice',
+      'slice full-id required (e.g. M001-S001)',
+      {},
+    );
+  }
+  const result = ffMergeSliceWorktree(parsed.sliceFullId, parsed.target, cwd);
+  stdout.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };