@nemus-cli/nemus 0.10.0 → 0.12.0

package/skills/nemus/references/reflect.md

@@ -0,0 +1,43 @@
+# Reflect — retrospective on recent sessions
+
+`nemus reflect` (alias `retro`) reads your recent workspaces' agent session
+transcripts and asks *your own* configured agent (claude/pi/opencode — no API key
+of Nemus's) to recommend concrete setup improvements: skills to add, missing
+`AGENTS.md`/context rules, missing connectivity/smoke tests, and prompt/workflow
+habits — each with a priority and an example.
+
+```bash
+nemus reflect                     # analyze the most recent workspaces (default 10)
+nemus reflect --limit 20          # widen the window
+nemus reflect --workspace <name>  # analyze a single workspace
+```
+
+Output / sharing:
+```bash
+nemus reflect --json              # structured report ({ ok:false, error } on failure)
+nemus reflect --markdown > reflection.md   # paste into an issue/PR
+nemus reflect --group-by kind     # group recommendations by kind (default: priority)
+```
+
+Review saved reports (each run is saved under `~/.nemus/reflect/` unless
+`--no-save`):
+```bash
+nemus reflect history             # list saved reports
+nemus reflect show [id]           # show one (id or id-prefix; defaults to latest)
+```
+
+## Flags
+
+| Flag | Description |
+|---|---|
+| `--limit <n>` / `-n` | How many recent workspaces to analyze (default 10) |
+| `--workspace <name>` / `-w` | Analyze a single workspace (ignores `--limit`) |
+| `--json` | Structured JSON report to stdout |
+| `--markdown` | Markdown report to stdout |
+| `--group-by <how>` | `priority` (default) or `kind` |
+| `--no-save` | Don't save the report to `~/.nemus/reflect/` |
+| `--model` / `--thinking` | Judge model / pi thinking-level overrides |
+| `--dry-run` | Print the assembled corpus + judge prompt without calling the agent |
+
+Read-only and safe — it analyzes transcripts and prints advice; it changes no
+repos. Use it to coach setup, not to modify anything.

package/skills/nemus/references/save-context.md

@@ -0,0 +1,25 @@
+# Save Context
+
+`nemus save-context` (alias `ctx`) writes a progress summary to the workspace's
+`CONTEXT.md`, so work survives `/clear` or a new session. Read `CONTEXT.md` back
+at the start of a session to resume. The workspace defaults to the current
+directory; pass `-w` to target another.
+
+```bash
+nemus save-context -m "…"                 # save to the current workspace
+nemus save-context -w <name> -m "…"       # target a specific workspace
+nemus save-context                        # interactive: prompts for the summary
+nemus save-context -f notes.md --append   # read from a file, append (don't replace)
+```
+
+Use it to capture: what was done, what's in progress, key decisions, and the
+next steps — before a context reset or when handing off.
+
+## Flags
+
+| Flag | Short | Description |
+|---|---|---|
+| `--workspace <name>` | `-w` | Workspace name (default: current directory) |
+| `--message <text>` | `-m` | Summary text to save (skips the prompt) |
+| `--file <path>` | `-f` | Read the summary from a file |
+| `--append` | | Append to existing context instead of replacing |

package/skills/prune-workspaces.md

@@ -0,0 +1,23 @@
+---
+name: prune-workspaces
+description: Bulk-delete workspaces with no recent activity, safe by default (protects uncommitted/unpushed work)
+---
+
+Preview first — never delete without showing the user the plan:
+```bash
+nemus prune --days 30 --dry-run
+```
+
+Then prune after confirming with the user:
+```bash
+nemus prune --days 30          # prompts (default: No)
+nemus prune --days 30 --yes    # non-interactive — only when the user is sure
+```
+
+- **Stale** = no agent session (or, failing that, no `createdAt`) in the last N
+  days (`--days`, default 30). Undatable workspaces are never selected.
+- **Safe by default:** workspaces with uncommitted or unpushed changes are
+  **protected** and listed with the reason — not deleted. `--include-dirty`
+  overrides this (only with explicit user consent to lose that work).
+- `--json` and `--dry-run` never delete.
+- Deletion is permanent — repos must be re-cloned. Always confirm first.

package/skills/reflect.md

@@ -0,0 +1,21 @@
+---
+name: reflect
+description: Retrospective on recent agent sessions — get concrete tips to improve skills, context, and prompts
+---
+
+Analyze recent workspaces' agent sessions and get setup improvement tips (read-only; changes no repos):
+```bash
+nemus reflect                     # most recent workspaces (default 10)
+nemus reflect --workspace <name>  # a single workspace
+nemus reflect --markdown > reflection.md   # shareable report
+```
+
+Review saved reports (saved under `~/.nemus/reflect/` unless `--no-save`):
+```bash
+nemus reflect history      # list past reports
+nemus reflect show [id]    # show one (defaults to latest)
+```
+
+- Uses *your own* configured agent (claude/pi/opencode) as the judge — no API key of Nemus's.
+- `--json` / `--markdown` for machine or shareable output; `--group-by kind|priority`.
+- Safe: it reads transcripts and prints advice, nothing is modified.

package/src/commands/prune.ts

@@ -0,0 +1,183 @@
+import { Command } from 'commander';
+import * as fs from 'fs/promises';
+import { safeWorkspacePath } from '../utils/validation';
+import { listWorkspaces } from '../utils/workspace-meta';
+import { getWorkspaceSessions } from '../utils/claude-sessions';
+import { getAllReposStatus } from '../utils/git-status';
+import { logInfo, logSuccess, logError, logWarning, logStep } from '../utils/logger';
+import { colorize } from '../utils/colors';
+import { confirm } from '../utils/prompt';
+import { getGlobalOpts } from '../utils/command-helpers';
+import { outputJson, outputJsonError } from '../utils/output';
+import {
+  toCandidate,
+  isStale,
+  planPrune,
+  type WorkspaceForPrune,
+  type PruneCandidate,
+} from '../utils/prune';
+
+const DEFAULT_DAYS = 30;
+
+export function registerPruneCommand(parent: Command) {
+  parent
+    .command('prune')
+    .description('Delete workspaces with no recent activity (safe by default)')
+    .option('-d, --days <n>', `Consider a workspace stale after N days of inactivity (default ${DEFAULT_DAYS})`)
+    .option('--include-dirty', 'Also prune workspaces with uncommitted/unpushed changes (default: protected)')
+    .option('--dry-run', 'Show what would be pruned without deleting anything')
+    .option('-y, --yes', 'Skip the confirmation prompt')
+    .option('--json', 'Output the prune plan as JSON (never deletes)')
+    .action(async (opts, cmd) => {
+      const globalOpts = getGlobalOpts(cmd);
+      await handlePrune({ ...opts, ...globalOpts });
+    });
+}
+
+function parseDays(raw: unknown): number | null {
+  if (raw === undefined) return DEFAULT_DAYS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return Math.floor(n);
+}
+
+export async function handlePrune(opts: {
+  days?: string;
+  includeDirty?: boolean;
+  dryRun?: boolean;
+  yes?: boolean;
+  json?: boolean;
+}) {
+  const json = !!opts.json;
+  const days = parseDays(opts.days);
+  if (days === null) {
+    if (json) outputJsonError('--days must be a non-negative number');
+    else logError('--days must be a non-negative number');
+    process.exit(1);
+  }
+
+  try {
+    const [workspaces, sessions] = await Promise.all([listWorkspaces(), getWorkspaceSessions()]);
+    const sessionMap = new Map(sessions.map((s) => [s.workspaceName, s]));
+    const now = Date.now();
+
+    const candidates: PruneCandidate[] = workspaces.map((ws) => {
+      const session = sessionMap.get(ws.name);
+      const createdRaw = ws.metadata?.createdAt ? Date.parse(ws.metadata.createdAt) : NaN;
+      const forPrune: WorkspaceForPrune = {
+        name: ws.name,
+        path: ws.path,
+        repoDirNames: (ws.metadata?.repositories ?? []).map((r) => r.directoryName),
+        lastActiveAt: session ? session.lastActiveAt.getTime() : 0,
+        createdAt: Number.isFinite(createdRaw) ? createdRaw : 0,
+      };
+      return toCandidate(forPrune, now);
+    });
+
+    const stale = candidates.filter((c) => isStale(c, days));
+
+    if (stale.length === 0) {
+      if (json) {
+        outputJson({ ok: true, days, prunable: [], protected: [], scanned: workspaces.length });
+      } else {
+        logInfo(`No workspaces inactive for ${days}+ days (scanned ${workspaces.length}).`);
+      }
+      return;
+    }
+
+    // Compute the plan. The git safety check only runs for stale workspaces.
+    const plan = await planPrune(
+      stale,
+      (c) => getAllReposStatus(c.path, c.repoDirNames, 3),
+      !!opts.includeDirty,
+    );
+
+    if (json) {
+      outputJson({
+        ok: true,
+        days,
+        scanned: workspaces.length,
+        prunable: plan.prunable.map((c) => ({ name: c.name, path: c.path, ageDays: c.ageDays, repos: c.repoDirNames.length })),
+        protected: plan.protected.map((p) => ({ name: p.candidate.name, ageDays: p.candidate.ageDays, reason: p.reason })),
+      });
+      return;
+    }
+
+    // Human report.
+    console.log('\n' + '='.repeat(60));
+    console.log(colorize(`Prune — workspaces inactive for ${days}+ days`, 'bright'));
+    console.log('='.repeat(60) + '\n');
+
+    if (plan.protected.length > 0) {
+      logWarning(`Protected (${plan.protected.length}) — skipped due to unsaved work:`);
+      for (const p of plan.protected) {
+        console.log(`  ${colorize('•', 'yellow')} ${colorize(p.candidate.name, 'cyan')} — ${p.reason} ${colorize(`(${ageLabel(p.candidate)})`, 'gray')}`);
+      }
+      console.log('');
+    }
+
+    if (plan.prunable.length === 0) {
+      logInfo('Nothing safe to prune.');
+      if (plan.protected.length > 0) logInfo('Re-run with --include-dirty to include the protected ones (careful).');
+      return;
+    }
+
+    console.log(`${colorize('Prunable', 'bright')} (${plan.prunable.length}):`);
+    for (const c of plan.prunable) {
+      const repoLabel = c.repoDirNames.length === 1 ? '1 repo' : `${c.repoDirNames.length} repos`;
+      console.log(`  ${colorize('✗', 'red')} ${colorize(c.name, 'cyan')} ${colorize(`(${ageLabel(c)}, ${repoLabel})`, 'gray')}`);
+    }
+    console.log('');
+
+    if (opts.dryRun) {
+      logInfo(`Dry run — nothing deleted. ${plan.prunable.length} workspace(s) would be pruned.`);
+      return;
+    }
+
+    logWarning('This permanently deletes the selected workspaces and every cloned repo inside them!');
+
+    if (!opts.yes) {
+      const confirmed = await confirm({
+        message: plan.prunable.length === 1
+          ? `Prune workspace ${plan.prunable[0].name}?`
+          : `Prune these ${plan.prunable.length} workspaces?`,
+        default: false,
+      });
+      if (!confirmed) {
+        logInfo('Prune cancelled');
+        return;
+      }
+    }
+
+    let deleted = 0;
+    for (const c of plan.prunable) {
+      let target: string;
+      try {
+        // Re-validate through the same choke point delete uses: enforces the
+        // name allowlist and pins the path inside WORKSPACES_DIR.
+        target = safeWorkspacePath(c.name);
+      } catch (error) {
+        logError(error instanceof Error ? error.message : `Invalid workspace name "${c.name}"`);
+        continue;
+      }
+      try {
+        await fs.rm(target, { recursive: true, force: true });
+        logSuccess(`Pruned "${colorize(c.name, 'cyan')}"`);
+        deleted++;
+      } catch (error) {
+        logError(`Failed to prune "${c.name}"`);
+        if (error instanceof Error) logError(error.message);
+      }
+    }
+    logStep(`Pruned ${deleted} of ${plan.prunable.length} workspace(s).`);
+  } catch (error) {
+    if (json) outputJsonError(error instanceof Error ? error.message : 'prune failed');
+    else logError(error instanceof Error ? error.message : 'prune failed');
+    process.exit(1);
+  }
+}
+
+function ageLabel(c: PruneCandidate): string {
+  const base = c.ageDays === 1 ? '1 day' : `${c.ageDays} days`;
+  return c.fromSession ? `${base} since last session` : `${base} since created, no sessions`;
+}

package/src/commands/version.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import { buildVersionInfo } from './version';
+
+describe('buildVersionInfo', () => {
+  it('combines the given version with the injected runtime fields', () => {
+    const info = buildVersionInfo('1.2.3', {
+      versions: { node: '22.13.0' } as NodeJS.ProcessVersions,
+      platform: 'linux',
+      arch: 'x64',
+    });
+    expect(info).toEqual({ version: '1.2.3', node: '22.13.0', platform: 'linux', arch: 'x64' });
+  });
+
+  it('defaults to the real process runtime', () => {
+    const info = buildVersionInfo('9.9.9');
+    expect(info.version).toBe('9.9.9');
+    expect(info.node).toBe(process.versions.node);
+    expect(info.platform).toBe(process.platform);
+    expect(info.arch).toBe(process.arch);
+  });
+});

package/src/commands/version.ts

@@ -0,0 +1,45 @@
+import { Command } from 'commander';
+import { outputJson } from '../utils/output';
+
+export interface VersionInfo {
+  version: string;
+  node: string;
+  platform: string;
+  arch: string;
+}
+
+/**
+ * Build the version payload. Pure and process-injectable so the JSON shape is
+ * unit-testable without reading the real runtime.
+ */
+export function buildVersionInfo(
+  version: string,
+  proc: Pick<NodeJS.Process, 'versions' | 'platform' | 'arch'> = process,
+): VersionInfo {
+  return {
+    version,
+    node: proc.versions.node,
+    platform: proc.platform,
+    arch: proc.arch,
+  };
+}
+
+/**
+ * `nemus version` — a subcommand companion to the `-V/--version` flag, for
+ * people who type `nemus version`. `--json` also reports the Node/OS runtime
+ * (handy for bug reports), emitting a single JSON document to stdout.
+ */
+export function registerVersionCommand(program: Command, version: string) {
+  program
+    .command('version')
+    .description('Print the Nemus version (with --json for version + runtime info)')
+    .option('--json', 'Output version + runtime info as JSON')
+    .action((opts: { json?: boolean }) => {
+      const info = buildVersionInfo(version);
+      if (opts.json) {
+        outputJson(info);
+      } else {
+        process.stdout.write(`nemus ${info.version}\n`);
+      }
+    });
+}

package/src/program.ts

@@ -4,6 +4,7 @@ import * as fs from 'fs';
 import { setColorEnabled } from './utils/colors';
 import { renderHelpBanner } from './utils/banner';
 import { applyGlobalFlags } from './utils/global-flags';
+import { registerVersionCommand } from './commands/version';
 
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -35,10 +36,12 @@ program
 program.hook('preAction', () => applyGlobalFlags(program.opts()));
 
 // Register top-level commands
+registerVersionCommand(program, pkg.version);
 import { registerCreateCommand } from './commands/create';
 import { registerListCommand } from './commands/list';
 import { registerUpdateCommand } from './commands/update';
 import { registerDeleteCommand } from './commands/delete';
+import { registerPruneCommand } from './commands/prune';
 import { registerSyncCommand } from './commands/sync';
 import { registerStatusCommand } from './commands/status';
 import { registerDiffCommand } from './commands/diff';
@@ -66,6 +69,7 @@ registerCreateCommand(program);
 registerListCommand(program);
 registerUpdateCommand(program);
 registerDeleteCommand(program);
+registerPruneCommand(program);
 registerSyncCommand(program);
 registerStatusCommand(program);
 registerDiffCommand(program);

package/src/utils/prune.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import {
+  toCandidate,
+  isStale,
+  protectionReason,
+  planPrune,
+  type WorkspaceForPrune,
+  type PruneCandidate,
+} from './prune';
+import type { GitStatus } from '../types';
+
+const NOW = Date.parse('2026-09-01T00:00:00Z');
+const daysAgo = (n: number) => NOW - n * 24 * 60 * 60 * 1000;
+
+function ws(over: Partial<WorkspaceForPrune> = {}): WorkspaceForPrune {
+  return { name: 'w', path: '/w', repoDirNames: [], lastActiveAt: 0, createdAt: 0, ...over };
+}
+function status(over: Partial<GitStatus> = {}): GitStatus {
+  return {
+    repo: 'r', branch: 'main', clean: true, ahead: 0, behind: 0,
+    modifiedFiles: 0, untrackedFiles: 0, hasRemote: true, detachedHead: false, ...over,
+  };
+}
+
+describe('toCandidate', () => {
+  it('prefers lastActive over createdAt and marks fromSession', () => {
+    const c = toCandidate(ws({ lastActiveAt: daysAgo(5), createdAt: daysAgo(40) }), NOW);
+    expect(c.fromSession).toBe(true);
+    expect(c.ageDays).toBe(5);
+    expect(c.undatable).toBe(false);
+  });
+
+  it('falls back to createdAt when there is no session', () => {
+    const c = toCandidate(ws({ lastActiveAt: 0, createdAt: daysAgo(40) }), NOW);
+    expect(c.fromSession).toBe(false);
+    expect(c.ageDays).toBe(40);
+  });
+
+  it('is undatable when neither timestamp is present', () => {
+    const c = toCandidate(ws({ lastActiveAt: 0, createdAt: 0 }), NOW);
+    expect(c.undatable).toBe(true);
+    expect(c.ageDays).toBe(0);
+  });
+
+  it('floors a future reference to a negative age (clock skew) without marking undatable', () => {
+    const c = toCandidate(ws({ lastActiveAt: NOW + 60_000 }), NOW);
+    expect(c.undatable).toBe(false);
+    expect(c.ageDays).toBeLessThan(0);
+  });
+});
+
+describe('isStale', () => {
+  const c = (over: Partial<WorkspaceForPrune>) => toCandidate(ws(over), NOW);
+
+  it('is true at or beyond the threshold', () => {
+    expect(isStale(c({ lastActiveAt: daysAgo(30) }), 30)).toBe(true);
+    expect(isStale(c({ lastActiveAt: daysAgo(31) }), 30)).toBe(true);
+  });
+  it('is false below the threshold', () => {
+    expect(isStale(c({ lastActiveAt: daysAgo(29) }), 30)).toBe(false);
+  });
+  it('never selects an undatable workspace', () => {
+    expect(isStale(c({ lastActiveAt: 0, createdAt: 0 }), 0)).toBe(false);
+  });
+  it('never selects a future-dated (skewed) workspace', () => {
+    expect(isStale(c({ lastActiveAt: NOW + 86_400_000 }), 0)).toBe(false);
+  });
+});
+
+describe('protectionReason', () => {
+  it('returns null for an all-clean workspace', () => {
+    expect(protectionReason([status(), status()], false)).toBeNull();
+  });
+  it('returns null for an empty workspace', () => {
+    expect(protectionReason([], false)).toBeNull();
+  });
+  it('flags uncommitted changes', () => {
+    expect(protectionReason([status({ clean: false })], false)).toBe('1 repo with uncommitted changes');
+  });
+  it('flags unpushed commits', () => {
+    expect(protectionReason([status({ ahead: 2 })], false)).toBe('1 repo with unpushed commits');
+  });
+  it('combines both reasons and pluralizes', () => {
+    expect(
+      protectionReason([status({ clean: false }), status({ clean: false }), status({ ahead: 1 })], false),
+    ).toBe('2 repos with uncommitted changes, 1 repo with unpushed commits');
+  });
+  it('returns null when includeDirty overrides protection', () => {
+    expect(protectionReason([status({ clean: false, ahead: 3 })], true)).toBeNull();
+  });
+});
+
+describe('planPrune', () => {
+  const mk = (name: string, repos: string[]): PruneCandidate =>
+    toCandidate(ws({ name, path: `/w/${name}`, repoDirNames: repos, lastActiveAt: daysAgo(40) }), NOW);
+
+  it('partitions prunable vs protected and skips git calls for empty workspaces', async () => {
+    const empty = mk('empty', []);
+    const clean = mk('clean', ['a']);
+    const dirty = mk('dirty', ['b']);
+    let calls = 0;
+    const resolver = async (c: PruneCandidate): Promise<GitStatus[]> => {
+      calls++;
+      return c.name === 'dirty' ? [status({ clean: false })] : [status()];
+    };
+
+    const plan = await planPrune([empty, clean, dirty], resolver, false);
+
+    expect(plan.prunable.map((c) => c.name)).toEqual(['empty', 'clean']);
+    expect(plan.protected.map((p) => p.candidate.name)).toEqual(['dirty']);
+    expect(plan.protected[0].reason).toBe('1 repo with uncommitted changes');
+    expect(calls).toBe(2); // empty workspace incurred no status call
+  });
+
+  it('includeDirty moves everything to prunable', async () => {
+    const dirty = mk('dirty', ['b']);
+    const plan = await planPrune([dirty], async () => [status({ clean: false, ahead: 2 })], true);
+    expect(plan.prunable.map((c) => c.name)).toEqual(['dirty']);
+    expect(plan.protected).toHaveLength(0);
+  });
+});

package/src/utils/prune.ts

@@ -0,0 +1,109 @@
+// Pure logic for `nemus prune` — deciding which workspaces are stale and which
+// are unsafe to delete. Kept free of I/O so it can be unit-tested exhaustively;
+// the command layer (src/commands/prune.ts) does the filesystem/git work and
+// feeds the results in here.
+import type { GitStatus } from '../types';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+export interface WorkspaceForPrune {
+  name: string;
+  path: string;
+  /** Repo directory names inside the workspace (for the git safety check). */
+  repoDirNames: string[];
+  /** Epoch ms of the most recent agent session, or 0 if none. */
+  lastActiveAt: number;
+  /** Epoch ms parsed from metadata.createdAt, or 0 if absent/unparseable. */
+  createdAt: number;
+}
+
+export interface PruneCandidate {
+  name: string;
+  path: string;
+  repoDirNames: string[];
+  /** The timestamp staleness is measured from (lastActive, else createdAt). */
+  referenceAt: number;
+  /** Whether the reference came from a real session (vs. createdAt fallback). */
+  fromSession: boolean;
+  /** Whole days since referenceAt (floored). */
+  ageDays: number;
+  /** True when we have no date at all to judge age. */
+  undatable: boolean;
+}
+
+export interface ProtectedWorkspace {
+  candidate: PruneCandidate;
+  reason: string;
+}
+
+export interface PrunePlan {
+  /** Stale + safe to delete. */
+  prunable: PruneCandidate[];
+  /** Stale but held back (uncommitted/unpushed work), unless includeDirty. */
+  protected: ProtectedWorkspace[];
+}
+
+/** Build a dated candidate for a workspace. `now` is injected for testability. */
+export function toCandidate(ws: WorkspaceForPrune, now: number): PruneCandidate {
+  const referenceAt = ws.lastActiveAt > 0 ? ws.lastActiveAt : ws.createdAt;
+  const undatable = !(referenceAt > 0);
+  const ageDays = undatable ? 0 : Math.floor((now - referenceAt) / MS_PER_DAY);
+  return {
+    name: ws.name,
+    path: ws.path,
+    repoDirNames: ws.repoDirNames,
+    referenceAt,
+    fromSession: ws.lastActiveAt > 0,
+    ageDays,
+    undatable,
+  };
+}
+
+/**
+ * A workspace is a prune candidate when it is datable and its age meets the
+ * threshold. Undatable workspaces are never auto-selected — we won't delete
+ * something we can't put a date on. A future `referenceAt` (clock skew) yields
+ * a negative age and is therefore not stale.
+ */
+export function isStale(c: PruneCandidate, days: number): boolean {
+  return !c.undatable && c.ageDays >= days;
+}
+
+/**
+ * Why a stale workspace should be held back from deletion, or null if it's safe.
+ * Unsafe = any repo has uncommitted changes (`!clean`) or unpushed commits
+ * (`ahead > 0`). With `includeDirty`, nothing is held back. An empty workspace
+ * (no repos) is always safe.
+ */
+export function protectionReason(statuses: GitStatus[], includeDirty: boolean): string | null {
+  if (includeDirty) return null;
+  const dirty = statuses.filter((s) => !s.clean).length;
+  const unpushed = statuses.filter((s) => s.ahead > 0).length;
+  if (dirty === 0 && unpushed === 0) return null;
+  const parts: string[] = [];
+  if (dirty > 0) parts.push(`${dirty} repo${dirty === 1 ? '' : 's'} with uncommitted changes`);
+  if (unpushed > 0) parts.push(`${unpushed} repo${unpushed === 1 ? '' : 's'} with unpushed commits`);
+  return parts.join(', ');
+}
+
+/**
+ * Partition stale candidates into prunable vs. protected, given a resolver that
+ * returns each workspace's per-repo git status. The resolver is only invoked
+ * for workspaces that actually have repos, so empty stale workspaces cost no git
+ * calls. Injecting the resolver keeps this function pure and unit-testable.
+ */
+export async function planPrune(
+  staleCandidates: PruneCandidate[],
+  getStatuses: (c: PruneCandidate) => Promise<GitStatus[]>,
+  includeDirty: boolean,
+): Promise<PrunePlan> {
+  const prunable: PruneCandidate[] = [];
+  const protectedList: ProtectedWorkspace[] = [];
+  for (const c of staleCandidates) {
+    const statuses = c.repoDirNames.length > 0 ? await getStatuses(c) : [];
+    const reason = protectionReason(statuses, includeDirty);
+    if (reason) protectedList.push({ candidate: c, reason });
+    else prunable.push(c);
+  }
+  return { prunable, protected: protectedList };
+}

package/src/utils/version-check.test.ts

@@ -24,14 +24,41 @@ vi.mock('./config', () => ({
   getPackageVersion: () => '2.20.0',
 }));
 
-import { checkForUpdate } from './version-check';
+import { checkForUpdate, updateCheckDisabled } from './version-check';
 import * as fs from 'fs/promises';
 
+describe('updateCheckDisabled', () => {
+  it('is true when NEMUS_NO_UPDATE_CHECK is set to a truthy value', () => {
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '1' })).toBe(true);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: 'yes' })).toBe(true);
+  });
+  it('honors the de-facto NO_UPDATE_NOTIFIER', () => {
+    expect(updateCheckDisabled({ NO_UPDATE_NOTIFIER: 'true' })).toBe(true);
+  });
+  it('is false when unset, empty, or an explicit falsey token', () => {
+    expect(updateCheckDisabled({})).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '' })).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '0' })).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: 'false' })).toBe(false);
+  });
+});
+
 describe('checkForUpdate', () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
+  it('returns null immediately when opted out via env (no fetch)', async () => {
+    process.env.NEMUS_NO_UPDATE_CHECK = '1';
+    try {
+      const result = await checkForUpdate();
+      expect(result).toBeNull();
+      expect(mockExecFile).not.toHaveBeenCalled();
+    } finally {
+      delete process.env.NEMUS_NO_UPDATE_CHECK;
+    }
+  });
+
   it('returns null when current version matches latest', async () => {
     // No cached check
     vi.mocked(fs.readFile).mockRejectedValueOnce(new Error('ENOENT'));