pi-pier 0.3.0 → 0.3.1

package/src/config-command.ts

@@ -1,39 +1,256 @@
 /**
- * D104 `/pier-config` command registration.
+ * D104 `/pier-config`: probes the four configuration planes (real files + process env), renders
+ * `show|check|doc|doctor`, and registers the command.
  *
- * Read-only by design: the command reports effective values with their provenance and
- * hands the actual edit to the agent under the existing write-lock + diff-confirmation
- * flow. It never writes configuration itself (only the opt-in `doc` report).
- *
- * Subcommands: (none) | show [plane|all] | check | doc [path]
+ * Read-only by design: effective values are reported with their provenance and the actual edit goes
+ * to the agent under the write-lock + diff-confirmation flow; only the opt-in `doc` report writes a
+ * file. Fail-open: every read is wrapped, so a broken plane degrades to a reported issue instead of
+ * throwing into pi's command pipeline. All paths are injectable, so tests never touch a real home dir.
  */
 
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import { VERSION as PI_VERSION } from '@earendil-works/pi-coding-agent';
-import { CONFIG_PLANES, type ConfigPlaneId } from './config-catalog-core.ts';
+import { VERSION as piVersion, type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import {
+  CONFIG_PLANES,
+  checkEnvKnobs,
+  renderCheck,
+  renderIndex,
+  renderPlane,
+  renderReport,
+  resolveConfigKnobs,
+  resolveEnvKnobs,
+  type CheckReport,
+  type ConfigPlaneId,
+  type ResolvedKnob,
+} from './config-catalog-core.ts';
 import {
-  CONFIG_GUIDANCE_PROMPT,
-  collectConfigSnapshot,
-  guideCheckLines,
-  guideIndexLines,
-  guidePlaneLines,
-  guideReportMarkdown,
-  type ConfigGuideDeps,
-  type ConfigGuideSnapshot,
-} from './config-guide.ts';
+  defaultUserEfficiencyConfigFile,
+  defaultWorkspaceEfficiencyConfigFile,
+  loadPiNativeCompactionSettings,
+  validateEfficiencyConfig,
+} from './efficiency-config-core.ts';
+import { RESERVED_ROLE_NAMES, listRoleNames, loadRoleConfig, roleLayers } from './role-loader.ts';
 import { formatOptionRows } from './pier-options.ts';
 import { formatSwallowedErrors } from './swallow.ts';
 import { HERDR_PROTOCOL_EXPECTED } from './herdr-client.ts';
 
-export const CONFIG_COMMAND_NAME = 'pier-config';
-export const CONFIG_GUIDE_CUSTOM_TYPE = 'pi-herdr.config-guide';
-export const CONFIG_REPORT_FILENAME = 'config-report.md';
-export const CONFIG_REPORT_DIR = '.pi-herdr';
+export const CONFIG_GUIDANCE_PROMPT = [
+  '[PIER-CONFIG] The user wants to inspect or change pier configuration. Follow this workflow strictly:',
+  '',
+  '1. Ground yourself first: run `/pier-config show all` (or read the files) and use the reported EFFECTIVE VALUE and SOURCE',
+  '   (env > workspace > user > default). Only entries whose source is `default` are worth changing; an ignored workspace file',
+  '   (untrusted project) must be reported as such instead of edited blindly.',
+  '2. Route by plane:',
+  '   - efficiency (D100-D103): read `docs/efficiency-trial.md` before proposing values.',
+  '   - roles: read `docs/sidebar-role-config.md` and `schemas/role-manifest.schema.json`; builtin role names cannot be overridden.',
+  "   - pi (settings.json): recommend pi's own `/settings`; the only OCC-relevant keys here are `compaction.enabled` and",
+  '     `compaction.keepRecentTokens` (read-only from our side).',
+  '   - env (PIER_* / PI_HERDR_*): affects new processes only; state that explicitly.',
+  '3. Explain before changing: 2-3 sentences on what the knob controls, its cost/benefit (tokens, latency, safety, blast radius),',
+  '   and 2-3 recommended values for common scenarios. Then ask what the user actually wants to achieve.',
+  '4. Before writing: show a precise diff (file path, current -> proposed value) and the activation path',
+  '   (hot / needs `/reload` / needs a new session or process restart). Wait for explicit confirmation. Change ONE plane at a time.',
+  '5. Apply with the normal `edit`/`write` tools (write locks apply), then run `/pier-config check` and report the result back.',
+  '6. If a change cannot take effect in the current process, say so and tell the user exactly what to restart.',
+  '',
+  'Forbidden: dumping `process.env`; writing secrets or tokens into any config file; editing multiple planes before confirmation;',
+  'touching `.pi-herdr/` of an untrusted project.',
+].join('\n');
 
-const PLANE_IDS: readonly ConfigPlaneId[] = CONFIG_PLANES.map((p) => p.id);
-const SUBCOMMANDS = ['show', 'check', 'doc', 'doctor'] as const;
+export interface ConfigPlaneFile {
+  readonly path: string;
+  readonly label: string;
+  readonly exists: boolean;
+  readonly ignored?: boolean;
+}
+
+export interface ConfigGuideDeps {
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  isProjectTrusted?: boolean;
+  /** Pi agent dir holding settings.json (defaults to ~/.pi/agent; mirrors PI_CODING_AGENT_DIR). */
+  agentDir?: string;
+  /** User-level efficiency config path (defaults to ~/.pi/agent/herdr-pi/config.json). */
+  userConfigPath?: string;
+  /** User-level roles dir override (defaults to ~/.pi/agent/herdr-pi/roles). */
+  rolesUserDir?: string;
+}
+
+export interface ConfigGuideSnapshot {
+  readonly entries: readonly ResolvedKnob[];
+  readonly reports: readonly CheckReport[];
+  readonly files: Readonly<Record<ConfigPlaneId, readonly ConfigPlaneFile[]>>;
+  readonly workspaceTrusted: boolean;
+  readonly roleSummary: string;
+}
+
+
+function readJsonLayer(path: string): { value: unknown; issue?: string } {
+  if (!existsSync(path)) return { value: undefined };
+  try {
+    return { value: JSON.parse(readFileSync(path, 'utf8')) };
+  } catch (err) {
+    return { value: undefined, issue: `${path}: invalid JSON (${err instanceof Error ? err.message : String(err)})` };
+  }
+}
+
+function listJsonFiles(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+  } catch {
+    return [];
+  }
+}
+
+export function collectConfigSnapshot(deps: ConfigGuideDeps = {}): ConfigGuideSnapshot {
+  const env = deps.env ?? process.env;
+  const cwd = deps.cwd ?? process.cwd();
+  const workspaceTrusted = deps.isProjectTrusted ?? false;
+  const agentDir = deps.agentDir ?? env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
+  const userConfigPath = deps.userConfigPath ?? defaultUserEfficiencyConfigFile();
+  const workspaceConfigPath = defaultWorkspaceEfficiencyConfigFile(cwd);
+
+  const reports: CheckReport[] = [];
+  const files: Record<ConfigPlaneId, ConfigPlaneFile[]> = { efficiency: [], roles: [], pi: [], env: [] };
+
+  /* efficiency: workspace layer (trusted projects only) + user layer, JSON issues reported as-is */
+  const workspaceLayer = readJsonLayer(workspaceConfigPath);
+  const userLayer = readJsonLayer(userConfigPath);
+  const efficiencyIssues: string[] = [];
+  for (const layer of [workspaceLayer, userLayer]) if (layer.issue) efficiencyIssues.push(layer.issue);
+  if (workspaceLayer.value !== undefined) {
+    if (workspaceTrusted) {
+      for (const issue of validateEfficiencyConfig(workspaceLayer.value).issues) efficiencyIssues.push(`${workspaceConfigPath}: ${issue}`);
+    } else {
+      efficiencyIssues.push(`${workspaceConfigPath}: ignored — the project is not trusted (values below come from user/default)`);
+    }
+  }
+  if (userLayer.value !== undefined) {
+    for (const issue of validateEfficiencyConfig(userLayer.value).issues) efficiencyIssues.push(`${userConfigPath}: ${issue}`);
+  }
+  files.efficiency.push(
+    { path: workspaceConfigPath, label: 'workspace', exists: workspaceLayer.value !== undefined, ignored: !workspaceTrusted },
+    { path: userConfigPath, label: 'user', exists: userLayer.value !== undefined },
+  );
+
+  /* pi settings (read-only here; only compaction.* matters to pier) */
+  const piSettingsPath = join(agentDir, 'settings.json');
+  const piSettingsExists = existsSync(piSettingsPath);
+  const piSettings = loadPiNativeCompactionSettings({ cwd, isProjectTrusted: workspaceTrusted, agentDir });
+  const piIssues = piSettingsExists
+    ? []
+    : [`${piSettingsPath}: not found (pi defaults apply; use pi's /settings to create it)`];
+  files.pi.push({ path: piSettingsPath, label: 'agent', exists: piSettingsExists });
+
+  const envIssues = checkEnvKnobs(env);
+  files.env.push({ path: '(process environment)', label: 'env', exists: true });
+
+  /* roles: every layer's JSON must load; builtin names are intentionally shadow-proof */
+  const roleIssues: string[] = [];
+  const roleNames = new Set<string>();
+  const layerCounts: string[] = [];
+  for (const layer of roleLayers({ baseDir: cwd, userDir: deps.rolesUserDir })) {
+    const names = listJsonFiles(layer.dir);
+    const label: ConfigPlaneFile['label'] = layer.label.startsWith('workspace')
+      ? 'workspace'
+      : layer.label.startsWith('user') ? 'user' : 'builtin';
+    files.roles.push({ path: layer.dir, label, exists: names.length > 0 });
+    layerCounts.push(`${label} ${names.length}`);
+    for (const file of names) roleNames.add(file.replace(/\.json$/, ''));
+  }
+  for (const name of [...roleNames].sort()) {
+    try {
+      loadRoleConfig(name, { baseDir: cwd });
+    } catch (err) {
+      const issues = (err as { issues?: readonly string[] }).issues ?? [];
+      roleIssues.push(`role "${name}": ${err instanceof Error ? err.message : String(err)}${issues.length ? ` — ${issues.join('; ')}` : ''}`);
+    }
+  }
+  const shadowed = listRoleNames(cwd, deps.rolesUserDir).filter((name) => RESERVED_ROLE_NAMES.includes(name));
+  if (shadowed.length > 0) {
+    roleIssues.push(`reserved role name(s) shadowed in a custom layer (ignored for built-ins): ${shadowed.join(', ')}`);
+  }
+  const roleSummary = `${roleNames.size} role(s): ${layerCounts.join(' / ')}`;
+
+
+  reports.push(
+    { plane: 'efficiency', ok: efficiencyIssues.length === 0, issues: efficiencyIssues },
+    { plane: 'roles', ok: roleIssues.length === 0, issues: roleIssues },
+    { plane: 'pi', ok: true, issues: piIssues },
+    { plane: 'env', ok: envIssues.length === 0, issues: envIssues },
+  );
+  const entries = [
+    ...resolveConfigKnobs({ env, workspace: workspaceLayer.value, user: userLayer.value, workspaceTrusted, piSettings }),
+    ...resolveEnvKnobs(env),
+  ];
+  return { entries, reports, files, workspaceTrusted, roleSummary };
+}
+
+
+export type GuideView = 'index' | 'check' | ConfigPlaneId | 'all';
+
+/** Renders one `/pier-config` view: the plane index, one/all plane listings, or the check report. */
+export function renderGuide(snapshot: ConfigGuideSnapshot, view: GuideView): string[] {
+  if (view === 'index') {
+    const plane = (id: ConfigPlaneId): readonly ResolvedKnob[] => snapshot.entries.filter((e) => e.knob.plane === id);
+    return renderIndex({
+      efficiency: plane('efficiency'),
+      pi: plane('pi'),
+      env: plane('env'),
+      roleSummary: snapshot.roleSummary,
+    });
+  }
+  if (view === 'check') {
+    const anyFail = snapshot.reports.some((r) => !r.ok);
+    return [
+      ...renderCheck(snapshot.reports),
+      anyFail ? '  → fix the FAIL planes above (values are still shown by `show`)' : '  → all planes look consistent',
+    ];
+  }
+
+  const out: string[] = [];
+  for (const meta of CONFIG_PLANES) {
+    if (view !== 'all' && meta.id !== view) continue;
+    out.push(`${meta.id} — ${meta.title}`);
+    for (const file of snapshot.files[meta.id]) {
+      const status = file.exists ? (file.ignored ? 'present (IGNORED: untrusted project)' : 'present') : 'absent';
+      out.push(`  file [${file.label}] ${file.path} — ${status}`);
+    }
+    out.push(`  hint: ${meta.editHint}`);
+    const entries = snapshot.entries.filter((e) => e.knob.plane === meta.id);
+    if (entries.length > 0) {
+      out.push(...renderPlane(entries));
+    } else {
+      const report = snapshot.reports.find((r) => r.plane === meta.id);
+      out.push(`  (per-file plane: ${!report ? 'no data' : report.ok ? 'no issues' : `${report.issues.length} issue(s) — see /pier-config check`})`);
+    }
+    out.push('');
+  }
+  return out;
+}
+
+export function guideReportMarkdown(
+  snapshot: ConfigGuideSnapshot,
+  meta: { generatedAt: string; cwd: string; piVersion?: string },
+): string {
+  const body = renderReport(snapshot.entries, {
+    generatedAt: meta.generatedAt,
+    cwd: meta.cwd,
+    workspaceTrusted: snapshot.workspaceTrusted,
+    piVersion: meta.piVersion,
+  });
+  const filesSection = ['', '## Files observed', ''];
+  for (const plane of CONFIG_PLANES) {
+    for (const file of snapshot.files[plane.id]) {
+      const status = file.exists ? (file.ignored ? 'present, ignored (untrusted project)' : 'present') : 'absent';
+      filesSection.push(`- [${plane.id}] ${file.label}: \`${file.path}\` — ${status}`);
+    }
+  }
+  const checkSection = ['', '## Checks', '', ...renderGuide(snapshot, 'check').map((l) => `- ${l.trim()}`)];
+  return `${body}\n${filesSection.join('\n')}\n${checkSection.join('\n')}\n`;
+}
 
 export interface ConfigCommandDeps {
   pi: ExtensionAPI;
@@ -43,9 +260,8 @@ export interface ConfigCommandDeps {
   reportDir?: (cwd: string) => string;
 }
 
-function isPlaneId(value: string): value is ConfigPlaneId {
-  return (PLANE_IDS as readonly string[]).includes(value);
-}
+const PLANE_IDS: readonly ConfigPlaneId[] = CONFIG_PLANES.map((p) => p.id);
+const SUBCOMMANDS = ['show', 'check', 'doc', 'doctor'] as const;
 
 function parseArgs(args: unknown): { sub: (typeof SUBCOMMANDS)[number] | 'index'; rest: string } {
   const raw = typeof args === 'string'
@@ -64,25 +280,22 @@ function parseArgs(args: unknown): { sub: (typeof SUBCOMMANDS)[number] | 'index'
 export function installConfigCommand(deps: ConfigCommandDeps): void {
   const { pi } = deps;
   const collect = deps.collect ?? collectConfigSnapshot;
-  const reportDir = deps.reportDir ?? ((cwd: string) => join(cwd, CONFIG_REPORT_DIR));
+  const reportDir = deps.reportDir ?? ((cwd: string) => join(cwd, '.pi-herdr'));
 
-  pi.registerCommand(CONFIG_COMMAND_NAME, {
+  pi.registerCommand('pier-config', {
     description:
-      'Show pier configuration (5 planes) with effective values and sources; `check` validates them; `doctor` lists option values and swallowed errors; no argument hands a guided change to the agent',
+      'Show pier configuration (4 planes) with effective values and sources; `check` validates them; `doctor` lists option values and swallowed errors; no argument hands a guided change to the agent',
     getArgumentCompletions: (prefix: string) => {
       const tokens = (prefix ?? '').split(/\s+/);
       const head = tokens[0] ?? '';
       if (tokens.length <= 1) {
-        const candidates = ['show', 'check', 'doc', 'doctor', 'all', ...PLANE_IDS];
-        return candidates
+        return ['show', 'check', 'doc', 'doctor', 'all', ...PLANE_IDS]
           .filter((c) => c.startsWith(head))
           .map((c) => ({ value: c, label: c, description: c === 'doc' ? 'write a config report file' : undefined }));
       }
       if (head === 'show') {
         const last = tokens[tokens.length - 1] ?? '';
-        return ['all', ...PLANE_IDS]
-          .filter((c) => c.startsWith(last))
-          .map((c) => ({ value: c, label: c }));
+        return ['all', ...PLANE_IDS].filter((c) => c.startsWith(last)).map((c) => ({ value: c, label: c }));
       }
       return null;
     },
@@ -110,24 +323,22 @@ export function installConfigCommand(deps: ConfigCommandDeps): void {
       const { sub, rest } = parseArgs(args);
 
       if (sub === 'check') {
-        emit([`pier config check (workspace trusted: ${snapshot.workspaceTrusted})`, ...guideCheckLines(snapshot)].join('\n'));
+        emit([`pier config check (workspace trusted: ${snapshot.workspaceTrusted})`, ...renderGuide(snapshot, 'check')].join('\n'));
         return;
       }
 
       if (sub === 'doc') {
-        const target = rest
-          ? (isAbsolute(rest) ? rest : resolve(cwd, rest))
-          : join(reportDir(cwd), CONFIG_REPORT_FILENAME);
+        const target = rest ? (isAbsolute(rest) ? rest : resolve(cwd, rest)) : join(reportDir(cwd), 'config-report.md');
         try {
           mkdirSync(dirname(target), { recursive: true });
           writeFileSync(
             target,
-            guideReportMarkdown(snapshot, { generatedAt: new Date().toISOString(), cwd, piVersion: PI_VERSION }),
+            guideReportMarkdown(snapshot, { generatedAt: new Date().toISOString(), cwd, piVersion }),
             'utf8',
           );
           emit(
-            `pier config report written: ${target}` +
-              (rest ? '' : '  (add `.pi-herdr/config-report.md` to .gitignore if you do not want it tracked)'),
+            `pier config report written: ${target}`
+              + (rest ? '' : '  (add `.pi-herdr/config-report.md` to .gitignore if you do not want it tracked)'),
           );
         } catch (err) {
           emit(`pier-config: could not write report (${err instanceof Error ? err.message : String(err)})`, 'error');
@@ -136,41 +347,37 @@ export function installConfigCommand(deps: ConfigCommandDeps): void {
       }
 
       if (sub === 'doctor') {
-        // B9/B10: one place to see every pier option (canonical name, effective value, source) and the
-        // errors that were deliberately swallowed this session. Without it, a silently failing
-        // best-effort path stays invisible until something else breaks.
-        emit(
-          [
-            'pier doctor',
-            '',
-            `wire: herdr protocol ${HERDR_PROTOCOL_EXPECTED} (pinned by test/fixtures/herdr-contract.json)`,
-            '',
-            `options (canonical PIER_*, legacy PI_HERDR_* alias accepted):`,
-            ...formatOptionRows(),
-            '',
-            formatSwallowedErrors(),
-          ].join('\n'),
-        );
+        // B9/B10: one place for every pier option (canonical name, effective value, source) and the
+        // errors deliberately swallowed this session — otherwise a failing best-effort path stays invisible.
+        emit([
+          'pier doctor',
+          '',
+          `wire: herdr protocol ${HERDR_PROTOCOL_EXPECTED} (pinned by test/fixtures/herdr-contract.json)`,
+          '',
+          'options (canonical PIER_*, legacy PI_HERDR_* alias accepted):',
+          ...formatOptionRows(),
+          '',
+          formatSwallowedErrors(),
+        ].join('\n'));
         return;
       }
 
       if (sub === 'show') {
         const plane = rest.trim();
-        const selector = plane === '' || plane === 'all' ? 'all' : isPlaneId(plane) ? plane : null;
-        if (selector === null) {
+        const selector = plane === '' || plane === 'all' ? 'all' : PLANE_IDS.find((id) => id === plane);
+        if (!selector) {
           emit(`pier-config: unknown plane "${plane}" — expected one of ${PLANE_IDS.join(', ')} or all`, 'warning');
           return;
         }
-        emit(guidePlaneLines(snapshot, selector).join('\n'));
+        emit(renderGuide(snapshot, selector).join('\n'));
         return;
       }
 
-      // Bare `/pier-config`: index + hand the guided change to the agent.
-      emit([...guideIndexLines(snapshot), '', 'asking the agent to guide the change...'].join('\n'));
+      emit([...renderGuide(snapshot, 'index'), '', 'asking the agent to guide the change...'].join('\n'));
       try {
         // Call on the receiver: the ExtensionAPI method must not be detached from `pi`.
         (pi as { sendMessage?: (msg: unknown, opts: unknown) => void }).sendMessage?.(
-          { customType: CONFIG_GUIDE_CUSTOM_TYPE, content: CONFIG_GUIDANCE_PROMPT, display: false },
+          { customType: 'pi-herdr.config-guide', content: CONFIG_GUIDANCE_PROMPT, display: false },
           { triggerTurn: true },
         );
       } catch (err) {

package/src/dashboard-command.ts

@@ -1,5 +1,5 @@
 import type { HerdrClientLike, HerdrEnv } from './herdr-client.ts';
-import type { TodoItem } from './vocab.ts';
+import { isTodoStatus, type TodoItem, type TodoStatus } from './vocab.ts';
 
 export interface DashboardCommandDeps {
   pi: {
@@ -11,6 +11,25 @@ export interface DashboardCommandDeps {
   getHeldLocks?: () => readonly string[];
 }
 
+/** SUMMARY_ORDER fixes the summary-line order; LIVE_ROWS adds the detail line below it.
+ * `abandoned` is counted in the total but never listed. */
+const SUMMARY_ORDER = [
+  { status: 'completed', label: 'done' },
+  { status: 'in_progress', label: 'working' },
+  { status: 'blocked', label: 'blocked' },
+  { status: 'pending', label: 'pending' },
+] as const;
+
+const LIVE_ROWS = [
+  { status: 'in_progress', label: 'Active', glyph: '▶', line: (todo: TodoItem) => todo.content },
+  {
+    status: 'blocked',
+    label: 'Blocked',
+    glyph: '■',
+    line: (todo: TodoItem) => `${todo.content}${todo.blocker ? ` (${todo.blocker})` : ''}`,
+  },
+] as const;
+
 export function formatStandaloneDashboard(opts: {
   todos: readonly TodoItem[];
   locks: readonly string[];
@@ -22,26 +41,27 @@ export function formatStandaloneDashboard(opts: {
   lines.push('Mode: Standalone (Non-Herdr / Local Session)');
   lines.push('--------------------------------------------------------------------------------');
 
-  const todos = opts.todos;
-  if (todos.length > 0) {
-    const inProg = todos.filter((t) => t.status === 'in_progress');
-    const blocked = todos.filter((t) => t.status === 'blocked');
-    const done = todos.filter((t) => t.status === 'completed');
-    const pending = todos.filter((t) => t.status === 'pending');
+  if (opts.todos.length === 0) {
+    lines.push('Todos: (none)');
+  } else {
+    const groups: Record<TodoStatus, TodoItem[]> = {
+      pending: [], in_progress: [], completed: [], blocked: [], abandoned: [],
+    };
+    // Corrupt snapshots can carry any status; a prototype key would make `groups[...].push` throw.
+    const todos = opts.todos.filter((todo) => isTodoStatus(todo.status));
+    for (const todo of todos) groups[todo.status].push(todo);
+
     lines.push(
-      `Todos: ${todos.length} total (${done.length} done, ${inProg.length} working, ${blocked.length} blocked, ${pending.length} pending)`,
+      `Todos: ${todos.length} total (${SUMMARY_ORDER.map((row) => `${groups[row.status].length} ${row.label}`).join(', ')})`,
     );
-    if (inProg.length > 0) {
-      lines.push(`Active: ▶ ${inProg.map((t) => t.content).join(', ')}`);
-    }
-    if (blocked.length > 0) {
-      lines.push(`Blocked: ■ ${blocked.map((t) => `${t.content}${t.blocker ? ` (${t.blocker})` : ''}`).join(', ')}`);
+    for (const row of LIVE_ROWS) {
+      const items = groups[row.status];
+      if (items.length > 0) lines.push(`${row.label}: ${row.glyph} ${items.map(row.line).join(', ')}`);
     }
-    if (inProg.length === 0 && blocked.length === 0 && done.length > 0) {
-      lines.push(`Completed: ✓ ${done.slice(-3).map((t) => t.content).join(', ')}`);
+    // Recent completions only carry signal when nothing is in flight.
+    if (groups.in_progress.length === 0 && groups.blocked.length === 0 && groups.completed.length > 0) {
+      lines.push(`Completed: ✓ ${groups.completed.slice(-3).map((todo) => todo.content).join(', ')}`);
     }
-  } else {
-    lines.push('Todos: (none)');
   }
 
   const locks = opts.locks;
@@ -58,7 +78,6 @@ export function installDashboardCommand(deps: DashboardCommandDeps): void {
     handler: async (_args, ctx) => {
       const ui = (ctx as { ui?: { notify?: (text: string, level?: string) => void } }).ui;
 
-      // Level 1 / Level 2: Herdr environment
       if (deps.client.available && deps.env) {
         try {
           const res = await deps.client.openPluginPane({
@@ -74,7 +93,7 @@ export function installDashboardCommand(deps: DashboardCommandDeps): void {
           }
           return;
         } catch {
-          // If plugin is not installed or socket error occurs, fall through to Level 3 local view
+          // Plugin missing or socket error: fall through to the Level 3 local view.
         }
       }