@polymorphism-tech/morph-spec 8.7.0 → 8.9.0

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # create-umbraco-lp

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # migrate-lp-to-umbraco

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-apply

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-plan

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-proposal

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.7.0"
+cliVersion: "8.9.0"
 ---
 
 # morph-standards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.7.0",
+  "version": "8.9.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/project/doctor.js

@@ -88,15 +88,109 @@ const REQUIRED_COMMAND_FILES = [
   'src/commands/context/context-refresh.js',
 ];
 
-// framework standards (stack-relevant only)
+/**
+ * Validate a parsed `agents.json` against the v5 contract.
+ *
+ * Exported, and pure, so the tests can exercise the REAL rules. They used to
+ * re-implement this logic inline "because doctorCommand doesn't export
+ * individual check functions" — and the two promptly disagreed: the tests
+ * asserted a v4 document (version 4.x, `tier` and `active_phases` required)
+ * while this code treats exactly those fields as deprecated. Both stayed green
+ * because they never met. A canary that destroyed this whole check left the
+ * suite at 18/18.
+ *
+ * @param {Object} agentsData - parsed agents.json
+ * @returns {Array<{name: string, status: 'ok'|'warn'|'error', msg?: string}>}
+ */
+export function validateAgentsJson(agentsData) {
+  const checks = [];
+  const agentEntries = Object.entries(agentsData.agents || {})
+    .filter(([k]) => !k.startsWith('_comment'));
+  const actualCount = agentEntries.length;
+  const declaredCount = agentsData.total_agents;
+
+  // 1: total_agents matches actual count
+  if (actualCount !== declaredCount) {
+    checks.push({
+      name: 'agents.json count',
+      status: 'warn',
+      msg: `total_agents declares ${declaredCount} but found ${actualCount} agents`
+    });
+  } else {
+    checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
+  }
+
+  // 2: required v5 personas present
+  const missingPersonas = REQUIRED_AGENTS.filter(id => !(agentsData.agents || {})[id]);
+  if (missingPersonas.length > 0) {
+    checks.push({
+      name: 'agents.json required personas',
+      status: 'error',
+      msg: `Missing required personas: ${missingPersonas.join(', ')}`
+    });
+  } else {
+    checks.push({ name: 'agents.json required personas', status: 'ok' });
+  }
+
+  // 3: v5 schema (flat personas, no tiers)
+  const version = agentsData.version || 'unknown';
+  const isV5 = version.startsWith('5.');
+  const v4Fields = [];
+  const missingV5Fields = [];
+
+  for (const [id, data] of agentEntries) {
+    if (data.tier !== undefined) v4Fields.push(`${id}.tier`);
+    if (data.active_phases !== undefined) v4Fields.push(`${id}.active_phases`);
+    if (data.reports_to !== undefined) v4Fields.push(`${id}.reports_to`);
+    if (data.teammate !== undefined) v4Fields.push(`${id}.teammate`);
+    if (!data.title) missingV5Fields.push(`${id}.title`);
+    if (!Array.isArray(data.domains)) missingV5Fields.push(`${id}.domains`);
+    if (typeof data.persona !== 'string' || !data.persona) missingV5Fields.push(`${id}.persona`);
+  }
+
+  if (isV5) {
+    checks.push({ name: `agents.json schema (v${version})`, status: 'ok' });
+  } else {
+    checks.push({
+      name: `agents.json schema (v${version})`,
+      status: 'warn',
+      msg: 'expected v5.x — run agents migration'
+    });
+  }
+
+  if (v4Fields.length > 0) {
+    const sample = v4Fields.slice(0, 3).join(', ');
+    checks.push({
+      name: 'agents.json deprecated v4 fields',
+      status: 'warn',
+      msg: `${v4Fields.length} v4 field(s) found: ${sample}${v4Fields.length > 3 ? '...' : ''}`
+    });
+  }
+
+  if (missingV5Fields.length > 0 && isV5) {
+    const sample = missingV5Fields.slice(0, 3).join(', ');
+    checks.push({
+      name: 'agents.json v5 required fields',
+      status: 'warn',
+      msg: `${missingV5Fields.length} missing: ${sample}${missingV5Fields.length > 3 ? '...' : ''}`
+    });
+  }
+
+  return checks;
+}
+
+// framework standards (stack-relevant only).
+// Keep every entry pointing at a file that exists: a check that can never pass
+// carries the same information as one that can never fail — none. This list
+// still named two standards from a `workflows/` directory that no longer
+// exists, which pinned `doctor --full` at a permanent 3/6 and made a real
+// regression indistinguishable from the usual red.
 const FRAMEWORK_STANDARDS = [
   'framework/standards/architecture/vertical-slice/vertical-slice.md',
   'framework/standards/data/nosql/cosmos-db.md',
   'framework/standards/data/nosql/cache/redis.md',
   'framework/standards/data/vector-search/rag-chunking.md',
-  'framework/standards/integration/mcp/mcp-tools.md',
-  'framework/standards/workflows/thread-management.md',
-  'framework/standards/workflows/parallel-execution.md'
+  'framework/standards/integration/mcp/mcp-tools.md'
 ];
 
 // required personas expected in agents.json (v5 — the universal, stack-agnostic
@@ -127,39 +221,61 @@ async function doctorFullCommand(frameworkRoot) {
     }
   };
 
-  // ── 1. Core Libraries ───────────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  src/lib/ — Core Libraries (${REQUIRED_LIB_FILES.length} files)`));
-  const missingLibs = [];
-  for (const f of REQUIRED_LIB_FILES) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingLibs.push(f.split('/').pop());
-  }
-  check(`Core Libraries (${REQUIRED_LIB_FILES.length - missingLibs.length}/${REQUIRED_LIB_FILES.length})`,
-    missingLibs.length === 0, false,
-    missingLibs.length > 0 ? `missing: ${missingLibs.join(', ')}` : '');
-
-  // ── 2. Command Files ─────────────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  src/commands/ — Command Files (${REQUIRED_COMMAND_FILES.length} files)`));
-  const missingCmds = [];
-  for (const f of REQUIRED_COMMAND_FILES) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingCmds.push(f.split('/').pop());
+  // Two layouts reach this command and they disagree on where everything is.
+  //
+  //   framework repo     src/, framework/, no .morph/ at all
+  //   installed project  .morph/framework/, and the CLI in node_modules
+  //
+  // Half the checks assumed one layout and half the other, so `--full` could
+  // not pass anywhere: red in the repo (no .morph/) and red in a project (no
+  // src/). A check that can never pass reports exactly as much as one that can
+  // never fail. Each check now runs only where it means something.
+  const installedAgentsPath = join(frameworkRoot, '.morph/framework/agents.json');
+  const canonicalAgentsPath = join(frameworkRoot, 'framework/agents.json');
+  const inFrameworkRepo = !(await pathExists(installedAgentsPath))
+    && await pathExists(canonicalAgentsPath);
+  const agentsPath = inFrameworkRepo ? canonicalAgentsPath : installedAgentsPath;
+
+  console.log(chalk.gray(`\n  Contexto: ${inFrameworkRepo ? 'repo do framework' : 'projeto instalado'}`));
+
+  // ── 1-2. Source tree (framework repo only) ──────────────────────────────
+  // An installed project has no src/ — the CLI lives in node_modules, and its
+  // integrity is npm's job, not the doctor's.
+  if (inFrameworkRepo) {
+    console.log(chalk.cyan(`\n  src/lib/ — Core Libraries (${REQUIRED_LIB_FILES.length} files)`));
+    const missingLibs = [];
+    for (const f of REQUIRED_LIB_FILES) {
+      if (!(await pathExists(join(frameworkRoot, f)))) missingLibs.push(f.split('/').pop());
+    }
+    check(`Core Libraries (${REQUIRED_LIB_FILES.length - missingLibs.length}/${REQUIRED_LIB_FILES.length})`,
+      missingLibs.length === 0, false,
+      missingLibs.length > 0 ? `missing: ${missingLibs.join(', ')}` : '');
+
+    console.log(chalk.cyan(`\n  src/commands/ — Command Files (${REQUIRED_COMMAND_FILES.length} files)`));
+    const missingCmds = [];
+    for (const f of REQUIRED_COMMAND_FILES) {
+      if (!(await pathExists(join(frameworkRoot, f)))) missingCmds.push(f.split('/').pop());
+    }
+    check(`Command Files (${REQUIRED_COMMAND_FILES.length - missingCmds.length}/${REQUIRED_COMMAND_FILES.length})`,
+      missingCmds.length === 0, false,
+      missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
   }
-  check(`Command Files (${REQUIRED_COMMAND_FILES.length - missingCmds.length}/${REQUIRED_COMMAND_FILES.length})`,
-    missingCmds.length === 0, false,
-    missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
 
   // ── 3. Framework Standards ───────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
+  // Same files, different root: the repo holds them at framework/standards/,
+  // an installed project at .morph/framework/standards/.
+  const stdsRoot = inFrameworkRepo ? frameworkRoot : join(frameworkRoot, '.morph');
+  console.log(chalk.cyan(`\n  ${inFrameworkRepo ? '' : '.morph/'}framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
   const missingStds = [];
   for (const f of FRAMEWORK_STANDARDS) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingStds.push(f.replace('framework/standards/', ''));
+    if (!(await pathExists(join(stdsRoot, f)))) missingStds.push(f.replace('framework/standards/', ''));
   }
   check(`Framework Standards (${FRAMEWORK_STANDARDS.length - missingStds.length}/${FRAMEWORK_STANDARDS.length})`,
     missingStds.length === 0, false,
     missingStds.length > 0 ? `missing: ${missingStds.join(', ')}` : '');
 
   // ── 5. Required Agents in agents.json ───────────────────────────────────
-  console.log(chalk.cyan(`\n  .morph/framework/agents.json — Required Agents (${REQUIRED_AGENTS.length})`));
-  const agentsPath = join(frameworkRoot, '.morph/framework/agents.json');
+  console.log(chalk.cyan(`\n  ${inFrameworkRepo ? 'framework' : '.morph/framework'}/agents.json — Required Agents (${REQUIRED_AGENTS.length})`));
   if (await pathExists(agentsPath)) {
     try {
       const agentsConfig = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
@@ -176,8 +292,10 @@ async function doctorFullCommand(frameworkRoot) {
   }
 
   // ── 6. agents.json version freshness ──────────────────────────────────
-  const canonicalAgentsPath = join(frameworkRoot, 'framework/agents.json');
-  if (await pathExists(agentsPath) && await pathExists(canonicalAgentsPath)) {
+  // Only meaningful for an installed project: it compares what was installed
+  // against the canonical source. In the framework repo the two are the same
+  // file, so the comparison is vacuous and is skipped.
+  if (!inFrameworkRepo && await pathExists(agentsPath) && await pathExists(canonicalAgentsPath)) {
     try {
       const installed = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
       const canonical = JSON.parse(await fs.readFile(canonicalAgentsPath, 'utf8'));
@@ -193,7 +311,9 @@ async function doctorFullCommand(frameworkRoot) {
   // agents.json is the single source of truth; the .claude/agents/morph-*.md
   // files are derived artifacts (ADR-001). Missing = broken dispatch (error);
   // stale/hand-edited or orphan = drift (warning).
-  if (await pathExists(agentsPath)) {
+  // Skipped in the framework repo: the generated `.claude/agents/morph-*.md`
+  // are an artifact of installing into a project, not of the source tree.
+  if (!inFrameworkRepo && await pathExists(agentsPath)) {
     console.log(chalk.cyan('\n  .claude/agents/ — Generated personas (drift vs agents.json)'));
     try {
       let projectTags = [];
@@ -661,82 +781,10 @@ export async function doctorCommand(options = {}) {
   if (await pathExists(agentsPath)) {
     try {
       const agentsData = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
-      const agentEntries = Object.entries(agentsData.agents || {})
-        .filter(([k]) => !k.startsWith('_comment'));
-      const actualCount = agentEntries.length;
-      const declaredCount = agentsData.total_agents;
-
-      // Check 1: total_agents matches actual count
-      if (actualCount !== declaredCount) {
-        checks.push({
-          name: 'agents.json count',
-          status: 'warn',
-          msg: `total_agents declares ${declaredCount} but found ${actualCount} agents`
-        });
-        hasWarnings = true;
-      } else {
-        checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
-      }
-
-      // Check 2: required v5 personas present
-      const requiredPersonas = REQUIRED_AGENTS;
-      const missingPersonas = requiredPersonas.filter(id => !agentsData.agents[id]);
-      if (missingPersonas.length > 0) {
-        checks.push({
-          name: 'agents.json required personas',
-          status: 'error',
-          msg: `Missing required personas: ${missingPersonas.join(', ')}`
-        });
-        hasErrors = true;
-      } else {
-        checks.push({ name: 'agents.json required personas', status: 'ok' });
-      }
-
-      // Check 3: v5 schema validation (flat personas, no tiers)
-      const version = agentsData.version || 'unknown';
-      const isV5 = version.startsWith('5.');
-      const v4Fields = [];
-      const missingV5Fields = [];
-
-      for (const [id, data] of agentEntries) {
-        if (data.tier !== undefined) v4Fields.push(`${id}.tier`);
-        if (data.active_phases !== undefined) v4Fields.push(`${id}.active_phases`);
-        if (data.reports_to !== undefined) v4Fields.push(`${id}.reports_to`);
-        if (data.teammate !== undefined) v4Fields.push(`${id}.teammate`);
-        if (!data.title) missingV5Fields.push(`${id}.title`);
-        if (!Array.isArray(data.domains)) missingV5Fields.push(`${id}.domains`);
-        if (typeof data.persona !== 'string' || !data.persona) missingV5Fields.push(`${id}.persona`);
-      }
-
-      if (isV5) {
-        checks.push({ name: `agents.json schema (v${version})`, status: 'ok' });
-      } else {
-        checks.push({
-          name: `agents.json schema (v${version})`,
-          status: 'warn',
-          msg: 'expected v5.x — run agents migration'
-        });
-        hasWarnings = true;
-      }
-
-      if (v4Fields.length > 0) {
-        const sample = v4Fields.slice(0, 3).join(', ');
-        checks.push({
-          name: 'agents.json deprecated v4 fields',
-          status: 'warn',
-          msg: `${v4Fields.length} v4 field(s) found: ${sample}${v4Fields.length > 3 ? '...' : ''}`
-        });
-        hasWarnings = true;
-      }
-
-      if (missingV5Fields.length > 0 && isV5) {
-        const sample = missingV5Fields.slice(0, 3).join(', ');
-        checks.push({
-          name: 'agents.json v5 required fields',
-          status: 'warn',
-          msg: `${missingV5Fields.length} missing: ${sample}${missingV5Fields.length > 3 ? '...' : ''}`
-        });
-        hasWarnings = true;
+      for (const c of validateAgentsJson(agentsData)) {
+        checks.push(c);
+        if (c.status === 'error') hasErrors = true;
+        else if (c.status === 'warn') hasWarnings = true;
       }
     } catch {
       checks.push({ name: 'agents.json', status: 'error', msg: 'invalid JSON' });

package/src/commands/state/approve.js

@@ -256,6 +256,31 @@ export async function approveCommand(featureName, gateName, options = {}) {
       }
     }
 
+    // Skipped-pause backstop: a gate whose recorded decision demanded a human
+    // pause (gateDecisions[gate].pause === true) cannot then be stamped by a
+    // non-human signature. The detection already existed — in gate-guard.js —
+    // but that hook is registered for `Write|Edit|AskUserQuestion`, and a Bash
+    // tool call fires no hook at all. Since MORPH.md requires gate approval to
+    // go through THIS command and forbids hand-editing the state, the only path
+    // the hook could ever see was the one the charter bans. The check belongs
+    // where the stamp is applied, not beside it.
+    //
+    // Gated on the RESOLVED `approvedBy`, matching the hotfix backstop above:
+    // an omitted --mode in a headless context also resolves to "auto" and must
+    // not slip through. `--force` does NOT bypass this either — it is the
+    // out-of-order recovery flag, a different concern. The way out is a human
+    // signature, or rewriting the decision that asked for the pause.
+    const decision = feature.gateDecisions?.[gateName];
+    if (decision?.pause === true && approvedBy === 'auto') {
+      console.error(chalk.red(`\n❌ O Gate "${gateName}" registrou pause:true — auto-aprovação não se aplica.`));
+      console.error(chalk.gray(`   Sinal: ${decision.reason || 'risco detectado'}`));
+      console.error(chalk.gray('   A decisão gravada exigia pausa humana. Aprove com --approver <nome>, num'));
+      console.error(chalk.gray('   terminal interativo, ou pela resposta humana via AskUserQuestion (state-sync).'));
+      console.error(chalk.gray('   Se o sinal de risco já não vale, regrave a decisão:'));
+      console.error(chalk.gray(`   morph-spec gate-decision ${featureName} ${gateName} --pause false --reason "<motivo>"\n`));
+      process.exit(1);
+    }
+
     let selfAssessed = false;
     if (gateName === 'review') {
       const evaluatorReport = join(process.cwd(), '.morph', 'features', featureName, '4-review', 'evaluator-report.md');

package/src/core/paths/output-schema.js

@@ -120,24 +120,6 @@ export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
   return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, leafSegment(entry));
 }
 
-/**
- * Human-readable path of a schema entry, relative to the feature directory.
- *
- * SINGLE source for the `morph-outputs` tables: `scripts/generate-refs.js`
- * writes them and `test/framework/refs.test.js` verifies them, and if the two
- * rebuilt the string independently they would drift apart the first time the
- * schema grew a new shape. Multi-file types render the filename PATTERN, so a
- * reader sees it's a folder of N files.
- *
- * @param {Object} entry - an OUTPUT_SCHEMA value
- * @returns {string} e.g. "2-plan/spec.md" or "2-plan/usecases/UC-{nn}-{slug}.md"
- */
-export function getSchemaDisplayPath(entry) {
-  return entry.multi
-    ? `${entry.phaseDir}/${entry.dirname}/${entry.displayFilename}`
-    : `${entry.phaseDir}/${entry.filename}`;
-}
-
 /**
  * Get the feature base directory (morph-relative, forward slashes).
  */

package/src/utils/hooks-installer.js

@@ -504,10 +504,16 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
     ? `"${resolvePythonForStatusline()}" "${join(globalDir, 'statusline.py').replace(/\\/g, '/')}"`
     : join(globalDir, 'statusline.sh').replace(/\\/g, '/');
 
+  // refreshInterval: without it the status line only re-renders on events
+  // (new assistant message, /compact, permission or vim mode change), so the
+  // `↻` countdown to the 5h rate-limit reset — the only widget that moves on
+  // its own — sits frozen through a long turn. Everything else is event-driven
+  // and would be fine without this.
   settings.statusLine = {
     type: 'command',
     command: statuslineCommand,
-    padding: 2
+    padding: 2,
+    refreshInterval: 10
   };
 
   await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');