trackfw 7.0.0 → 7.2.0

package/src/generators/init.js

@@ -723,6 +723,18 @@ function generateClaudeMD(cfg) {
   content += 'Decide low-risk details autonomously following existing project conventions, '
   content += 'and record autonomous decisions in the commit message.\n'
 
+  content += '\n## Architect responses\n\n'
+  content += 'Default: what changed · what was decided · what is needed from you. Three to five lines.\n\n'
+  content += 'Scale up only on these three triggers, and only on them: a **blocker** that stops the next wave; '
+  content += 'a **pending user decision** that cannot be inferred from context; '
+  content += 'an **error the architect made** that cannot be self-corrected.\n\n'
+  content += 'Never cut, even when short: measured evidence (command and result), barrier verdict, decision taken and why. '
+  content += 'A response that buries a blocker in paragraph seven produced the same effect as not reporting it.\n\n'
+  content += 'Cut: restating what an executor already reported, re-explaining reasoning already given, '
+  content += 'recapping state that has not changed, closing praise. '
+  content += 'Tables and code blocks only when they replace prose, never when they add to it.\n\n'
+  content += 'Depth is on demand from the user.\n'
+
   injectOrUpdateRules('CLAUDE.md', content, '.')
   console.log('  ✓ CLAUDE.md')
 }

package/src/i18n/locales/en-US.json

@@ -120,8 +120,5 @@
     "no_data": "No transitions recorded yet.",
     "since": "Filter by period (e.g. 7d, 30d, 90d)",
     "export": "Export metrics to CSV file"
-  },
-  "errors": {
-    "notFound": "Not found: {{path}}"
   }
 }

package/src/i18n/locales/es-ES.json

@@ -120,8 +120,5 @@
     "no_data": "No hay transiciones registradas aún.",
     "since": "Filtrar por período (ej: 7d, 30d, 90d)",
     "export": "Exportar métricas a archivo CSV"
-  },
-  "errors": {
-    "notFound": "No encontrado: {{path}}"
   }
 }

package/src/i18n/locales/pt-BR.json

@@ -120,8 +120,5 @@
     "no_data": "Nenhuma transição registrada ainda.",
     "since": "Filtrar por período (ex: 7d, 30d, 90d)",
     "export": "Exportar métricas para arquivo CSV"
-  },
-  "errors": {
-    "notFound": "Não encontrado: {{path}}"
   }
 }

package/src/integrations/assets/agents/architect.md

@@ -44,4 +44,16 @@ Before releasing the next wave, verify each acceptance criterion yourself: read
 ## Mission
 Map the existing architecture and traceability chain before proposing changes. Record material decisions as ADRs, produce decision-complete plans, and delegate implementation to the appropriate specialist. Do not implement product code.
 
+## Response length
+
+Default: what changed · what I decided · what I need from you. Three to five lines.
+
+Scale up only on these three triggers, and only on them: a **blocker** that stops the next wave; a **pending user decision** that cannot be inferred from context; an **error I made** that cannot be self-corrected.
+
+Never cut, even when short: measured evidence (command and result), barrier verdict, decision taken and why. A response that buries a blocker in paragraph seven produced the same effect as not reporting it.
+
+Cut: restating what an executor already reported, re-explaining reasoning already given, recapping state that has not changed, closing praise. Tables and code blocks only when they replace prose, never when they add to it.
+
+Depth is on demand from the user.
+
 — Architect, Principal Software Architect

package/src/integrations/index.js

@@ -56,7 +56,7 @@ function buildPlans(kind, options = {}) {
       for (const item of selected.itemEntries) {
         for (const installPath of paths) {
           const destination = installPath.path.replace('{{id}}', item.id)
-          let content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig })
+          let content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig, agentModels: options.agentModels || {} })
           // D5/D9 extension point: reproduce any persisted third-party
           // reference block so regenerating this exact artifact (e.g. a
           // later `trackfw agents update`) settles at state "current"

package/src/integrations/manager.js

@@ -30,6 +30,14 @@ class IntegrationManager {
   constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}, { onSkip } = {}) {
     this.roots = { project: path.resolve(projectRoot), global: path.resolve(homeRoot) }
     this.onSkip = onSkip
+    // _afterManifestPersist, when set, runs immediately after manifests are
+    // persisted and before artifact bytes are written during install/update
+    // (never during uninstall, which is intentionally not inverted — see the
+    // comment in mutate()). It exists only so tests can simulate an
+    // interruption exactly at the ADR-2026-08-18 ordering seam. Production
+    // code never assigns it. Mirrors internal/integrations/manager.go's
+    // afterManifestPersist package var.
+    this._afterManifestPersist = undefined
   }
 
   manifestPath(scope) { return path.join(this.roots[scope], '.trackfw', 'integrations-manifest.json') }
@@ -118,7 +126,16 @@ class IntegrationManager {
       const file = this.resolve(scope, plan.destination)
       const record = manifests.get(scope).artifacts[file]
       const managed = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
-      if (!fs.existsSync(file)) return { ...plan, destination: file, state: 'not-installed', managed }
+      // registered reports whether the manifest has ANY entry for this
+      // destination, regardless of claim ownership — unlike managed, which
+      // additionally requires this exact claim to own that entry. doctor
+      // (ML-2A) needs this distinction: a destination registered under a
+      // *different* claim must never be reported as an "unregistered
+      // write" — that would be the dominant false-positive doctor exists to
+      // avoid. Additive field; mirrors Inspection.Registered
+      // (internal/integrations/manager.go).
+      const registered = Boolean(record)
+      if (!fs.existsSync(file)) return { ...plan, destination: file, state: 'not-installed', managed, registered }
       const actual = sha256(fs.readFileSync(file))
       const desired = sha256(plan.content)
       let state
@@ -129,7 +146,7 @@ class IntegrationManager {
       } else if (actual === desired) state = 'current'
       else if ((plan.legacyHashes || []).includes(actual)) state = 'outdated'
       else state = 'modified'
-      return { ...plan, destination: file, state, managed }
+      return { ...plan, destination: file, state, managed, registered }
     })
   }
 
@@ -167,9 +184,44 @@ class IntegrationManager {
     const snapshots = new Map()
     for (const item of active) this.snapshot(snapshots, item.file)
     for (const scope of manifests.keys()) this.snapshot(snapshots, this.manifestPath(scope))
-    try {
-      for (const item of active) this.apply(operation, item, manifests.get(item.plan.claim.scope), force)
+    const saveManifests = () => {
       for (const [scope, manifest] of [...manifests].sort(([a], [b]) => a.localeCompare(b))) this.saveManifest(scope, manifest)
+    }
+    try {
+      // ADR-2026-08-18: install/update persist the manifest before writing
+      // artifact bytes (self-healing direction on interruption); uninstall
+      // keeps the original artifacts-before-manifest order. The two are
+      // deliberately NOT symmetric.
+      if (operation === 'uninstall') {
+        // Uninstall is not inverted. Removing bytes first and persisting the
+        // manifest last means an interruption leaves the manifest still
+        // declaring an artifact whose file is now absent — inspectResolved
+        // resolves that as 'not-installed', the same self-healing direction
+        // install/update get from the inversion below. Inverting uninstall
+        // the same way (drop the manifest entry, then remove bytes) would
+        // instead leave, on interruption, a file on disk whose content still
+        // matches the catalog template but with no manifest entry at all —
+        // reported as an orphaned state='current'/managed=false artifact
+        // that looks legitimate and that nothing detects or repairs
+        // automatically. That is exactly the "disk ahead of manifest" bad
+        // direction the ADR exists to eliminate, so uninstall must not be
+        // simetrized with install/update here. Mirrors the comment in
+        // internal/integrations/manager.go:mutate.
+        for (const item of active) this.applyUninstall(item, manifests.get(item.plan.claim.scope))
+        saveManifests()
+      } else {
+        // Install/Update: compute the manifest update for every active item
+        // in memory (no bytes touched yet), persist all manifests, and only
+        // then write the artifact bytes.
+        const pendingWrites = []
+        for (const item of active) {
+          const write = this.planArtifactWrite(operation, item, manifests.get(item.plan.claim.scope), force)
+          if (write) pendingWrites.push(write)
+        }
+        saveManifests()
+        if (typeof this._afterManifestPersist === 'function') this._afterManifestPersist()
+        for (const write of pendingWrites) this.atomicWrite(write.file, write.content, write.mode)
+      }
     } catch (error) {
       this.rollback(snapshots)
       throw error
@@ -186,7 +238,7 @@ class IntegrationManager {
       if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
       if (status.state === 'outdated' && owned && !force) return true // skip: bytes preserved, batch continues
     } else if (operation === 'update') {
-      if (!owned && status.state === 'modified') throw new Error(`Unmanaged artifact does not match a trackfw template: ${file}`)
+      if (!owned && status.state === 'modified') throw new Error(this.unmanagedArtifactError(file, plan.claim))
       if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
     } else if (operation === 'uninstall' && owned && status.state === 'modified' && !force) {
       throw new Error(`Artifact is modified; use --force: ${file}`)
@@ -256,19 +308,42 @@ class IntegrationManager {
     return { state: 'modified', managed: false }
   }
 
-  apply(operation, { plan, file }, manifest, force) {
+  // applyUninstall removes ownership of one artifact from the manifest, and —
+  // once no claim remains — the artifact's bytes and any empty ancestor
+  // directories it managed. It mutates disk directly (not deferred), because
+  // uninstall deliberately keeps the pre-ADR-2026-08-18 ordering: see the
+  // comment in mutate() for why this is not simetrized with
+  // planArtifactWrite. Mirrors internal/integrations/manager.go:applyUninstall.
+  applyUninstall({ plan, file }, manifest) {
+    const record = manifest.artifacts[file]
+    const key = claimKey(plan.claim)
+    const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === key))
+    if (!owned) return
+    record.claims = record.claims.filter(claim => claimKey(claim) !== key)
+    if (record.claims.length) return
+    if (fs.existsSync(file)) fs.unlinkSync(file)
+    delete manifest.artifacts[file]
+    this.cleanEmpty(path.dirname(file), this.roots[plan.claim.scope])
+  }
+
+  // planArtifactWrite computes the manifest update for one install/update
+  // item entirely in memory — it never touches the artifact's bytes on disk.
+  // The caller (mutate) persists every manifest in the batch first, and only
+  // then applies the returned pending write (ADR-2026-08-18). Returns null
+  // when no byte write is needed.
+  //
+  // The manifest values it stores are deliberately *optimistic* when a write
+  // is pending: sha256/catalog_version describe the content this call is
+  // about to write, not what is currently on disk. If interrupted before the
+  // pending write lands, the manifest already declares the target state and
+  // inspectResolved resolves the (absent or stale) file to
+  // 'not-installed'/'modified', both self-repairable by a later
+  // install/update, never modified+unowned ("unmanaged"). Mirrors
+  // internal/integrations/manager.go:planArtifactWrite.
+  planArtifactWrite(operation, { plan, file }, manifest, force) {
     let record = manifest.artifacts[file]
     const key = claimKey(plan.claim)
     const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === key))
-    if (operation === 'uninstall') {
-      if (!owned) return
-      record.claims = record.claims.filter(claim => claimKey(claim) !== key)
-      if (record.claims.length) return
-      if (fs.existsSync(file)) fs.unlinkSync(file)
-      delete manifest.artifacts[file]
-      this.cleanEmpty(path.dirname(file), this.roots[plan.claim.scope])
-      return
-    }
 
     const exists = fs.existsSync(file)
     let actual = exists ? sha256(fs.readFileSync(file)) : ''
@@ -278,16 +353,29 @@ class IntegrationManager {
     if (exists && !owned) writeDesired = (operation === 'update' && actual !== desired) || (force && actual !== desired)
     else if (exists && owned) writeDesired = actual !== desired
     if (!record) record = { destination: file, sha256: '', catalog_version: '', claims: [] }
+    let pending = null
     if (writeDesired) {
-      this.atomicWrite(file, plan.content, 0o644)
+      // Optimistic: bytes have not moved yet, but the manifest must already
+      // describe the content we are about to write (see doc comment above).
       actual = desired
+      pending = { file, content: plan.content, mode: 0o644 }
     } else if (exists && !owned && actual !== desired && !knownLegacy && !force) {
-      throw new Error(`Unmanaged artifact does not match a trackfw template: ${file}`)
+      // Defense-in-depth: preflight already rejects this exact case for
+      // 'update' (unconditionally) and for 'install' without --force (any
+      // state === 'modified' is blocked before an active item ever reaches
+      // planArtifactWrite()). This branch is therefore not reachable via
+      // install/update today, but stays as a second line of defense in case
+      // preflight's guard is ever loosened — hence the identical remediation
+      // text, so a user who somehow hits it still gets the same actionable
+      // message. No manifest mutation happens on this path. Mirrors
+      // internal/integrations/manager.go:planArtifactWrite.
+      throw new Error(this.unmanagedArtifactError(file, plan.claim))
     }
     if (!record.claims.some(claim => claimKey(claim) === key)) record.claims.push(cleanClaim(plan.claim))
     record.sha256 = actual
     record.catalog_version = actual === desired ? plan.catalogVersion : 'legacy'
     manifest.artifacts[file] = record
+    return pending
   }
 
   snapshot(snapshots, file) {
@@ -305,6 +393,19 @@ class IntegrationManager {
     }
   }
 
+  // unmanagedArtifactError — mensagem de erro para update/uninstall (ou,
+  // defensivamente, install) recusando bytes que o trackfw não escreveu.
+  // Nomeia o remédio — trackfw did not write these bytes, então a única forma
+  // segura de trazer o artefato sob gestão é `<kind> install --force`, que
+  // explicitamente autoriza adotar/substituir conteúdo unmanaged — com as
+  // flags exatas para reproduzir o claim deste plano (item, target, scope),
+  // prontas para copiar e colar. Espelha
+  // internal/integrations/manager.go:unmanagedArtifactError — fonte canônica
+  // do texto, byte a byte idêntica nos 3 CLIs.
+  unmanagedArtifactError(file, claim) {
+    return `unmanaged artifact "${file}" does not match a trackfw template — trackfw did not write these bytes.\nAdopt it with: trackfw ${claim.kind} install --force --items ${claim.item} --targets ${claim.target} --scope ${claim.scope}`
+  }
+
   // tildeAbbrev — retorna o caminho de exibição abreviado para uso em mensagens
   // de aviso de skip. Espelha internal/integrations/manager.go:tildeAbbrev.
   // - scope global: substitui homeRoot por '~' (via tildeify, com salvaguarda

package/src/integrations/render.js

@@ -97,6 +97,19 @@ function mapModelCursor(model) {
   return CURSOR_MODEL_MAP[model] || ''
 }
 
+// containsControlChar reports whether s contains any ASCII control character
+// (U+0000–U+001F) or a Unicode line/paragraph separator (U+2028, U+2029).
+// Mirrors internal/integrations/render.go:containsControlChar (ML-5C).
+// In JavaScript, strings are UTF-16; U+2028/U+2029 are single code units
+// accessible via charCodeAt, so no surrogate-pair handling is needed.
+function containsControlChar(s) {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c < 0x20 || c === 0x2028 || c === 0x2029) return true
+  }
+  return false
+}
+
 // rewriteFrontmatterModelLine substitui a linha "model:" do frontmatter de um
 // markdown cru por value, preservando toda outra linha do frontmatter e o
 // corpo byte a byte. Se o frontmatter não tiver linha "model:", uma é
@@ -105,7 +118,14 @@ function mapModelCursor(model) {
 // espelha a detecção de fronteira usada por rewriteFrontmatterFields,
 // escopada à chave única "model". Espelha
 // internal/integrations/render.go:rewriteFrontmatterModelLine.
+//
+// Throws an Error if value contains any ASCII control character (U+0000–U+001F).
+// Model IDs never require control characters; any such value is rejected to
+// prevent frontmatter injection (ML-5A).
 function rewriteFrontmatterModelLine(source, value) {
+  if (containsControlChar(value)) {
+    throw new Error(`model value contains control character and was rejected: model IDs never require newlines or other control characters (got ${JSON.stringify(value)})`)
+  }
   const trimmed = String(source).trim()
   if (!trimmed.startsWith('---\n')) return trimmed
   const end = trimmed.indexOf('\n---', 4)
@@ -296,6 +316,27 @@ function frontmatterName(content) {
   return undefined
 }
 
+// isVersionString reports whether s is a bare version string (digits and dots
+// only, e.g. "5", "4.6", "1.0.2"). Mirrors internal/integrations/render.go:isVersionString.
+// Values that don't match — pre-composed IDs like "claude-sonnet-4-5-20250929" (hyphens),
+// "latest" (letters), or "" (empty) — return false and the caller uses the value literally
+// (escape hatch, ADR-2026-08-21 §3).
+function isVersionString(s) {
+  if (!s) return false
+  return /^[0-9]+(\.[0-9]+)*$/.test(s)
+}
+
+// composeClaudeModelID builds a Claude model identifier from tier and version,
+// applying the three composition rules from the official Anthropic docs.
+// Mirrors internal/integrations/render.go:composeClaudeModelID.
+//   Rule 1: dots become hyphens ("4.6" → "claude-sonnet-4-6")
+//   Rule 2: major-only version never gets "-0" ("5" → "claude-sonnet-5")
+//   Rule 3: handled via escape hatch — pre-composed IDs are never version strings
+function composeClaudeModelID(tier, version) {
+  const hyphenated = version.replace(/\./g, '-')
+  return `claude-${tier}-${hyphenated}`
+}
+
 // render converte um item canônico do catálogo para a representação nativa
 // declarada por uma surface alvo. Quando identity carrega uma identidade
 // customizada para item.id, o name/description/body renderizados são
@@ -321,7 +362,12 @@ function frontmatterName(content) {
 // normalize(content) — a mesma expressão usada antes de existir suporte a
 // identidade — então a saída sem identidade é garantida byte a byte
 // inalterada por construção, não por coincidência.
-function render({ kind, content, capability, item, identity: cfg, target }) {
+//
+// agentModels (opcional) — objeto de tier→versão lido de trackfw.yaml's agent_models.
+// Ausente ou vazio: saída idêntica a antes. Somente o alvo "claude" recebe IDs
+// compostos; Codex, Cursor, Antigravity, OpenCode, Gemini, Kiro não são afetados
+// (ADR-2026-08-21 §4 — gate, não cuidado).
+function render({ kind, content, capability, item, identity: cfg, target, agentModels }) {
   if (kind === 'skills') return normalize(content)
 
   const id = item && cfg ? lookupIdentity(cfg, item.id) : undefined
@@ -407,6 +453,18 @@ function render({ kind, content, capability, item, identity: cfg, target }) {
   if (target === 'cursor') {
     const mappedModel = mapModelCursor(parts.model)
     source = mappedModel ? rewriteFrontmatterModelLine(source, mappedModel) : removeFrontmatterModelLine(source)
+  } else if (target === 'claude' && agentModels && Object.keys(agentModels).length > 0) {
+    // Allowlist: only the "claude" target receives composed model IDs.
+    // Codex, Cursor, Antigravity, OpenCode, Gemini, Kiro and any other target are left
+    // untouched even when agentModels is populated (ADR-2026-08-21 §4 — gate, not cuidado).
+    const version = agentModels[parts.model]
+    if (version) {
+      const modelID = isVersionString(version)
+        ? composeClaudeModelID(parts.model, version)
+        : version // escape hatch: non-version value used literally (ADR-2026-08-21 §3)
+      source = rewriteFrontmatterModelLine(source, modelID)
+    }
+    // Empty string version means "no pin": leave source unchanged (tier alias preserved).
   }
   if (!id) return normalize(source)
   const withBody = insertBodyPrefix(source, greeting)
@@ -415,4 +473,60 @@ function render({ kind, content, capability, item, identity: cfg, target }) {
   return normalize(withSignature)
 }
 
-module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteSignatureLine }
+// resolveAgentModel returns the model string that render() would write to the
+// model field of an artifact with the given representation and targetID, for
+// an agent with the given tier. Mirrors
+// internal/integrations/models.go:ResolveAgentModel.
+//
+// Returns { resolved: string, present: boolean }.
+// present=false means the artifact format omits the model field entirely — the
+// caller should display "—" or equivalent rather than the tier alias.
+//
+// agentModels applies only for the "claude" target (ADR-2026-08-21 §4).
+function resolveAgentModel(tier, representation, targetID, agentModels) {
+  if (representation === 'custom-agent-toml') {
+    const v = resolveModelCodex(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (representation === 'cli-agent-json' || representation === 'agent-json') {
+    return { resolved: '', present: false }
+  }
+  if (representation === 'agent-directory') {
+    const v = resolveModel(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (representation === 'opencode-agent') {
+    return { resolved: '', present: false }
+  }
+  // default branch — mirrors render()'s default case
+  if (targetID === 'cursor') {
+    const v = mapModelCursor(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (targetID === 'claude') {
+    const am = agentModels || {}
+    const version = am[tier]
+    if (version) {
+      const modelID = isVersionString(version) ? composeClaudeModelID(tier, version) : version
+      return { resolved: modelID, present: true }
+    }
+    // no pin → tier alias unchanged
+  }
+  return { resolved: tier, present: true }
+}
+
+// looksLikeSuspectModelValue reports whether v is an agent_models value that
+// will trigger the escape-hatch path and likely produce an invalid model
+// identifier in the rendered artifact. Returns true when v is not a bare
+// version string AND does not start with "claude-". Callers should emit a
+// per-tier warning to stderr (not per-row) when this returns true.
+// Mirrors internal/integrations/models.go:LooksLikeSuspectModelValue.
+// looksLikeSuspectModelValue mirrors internal/integrations/models.go:LooksLikeSuspectModelValue.
+// ML-5A: values with control characters are always suspect — rewriteFrontmatterModelLine
+// rejects them outright, so this function must agree with the write path to keep the
+// "agents models" inspection command aligned with "agents install/update" behavior.
+function looksLikeSuspectModelValue(v) {
+  return containsControlChar(v) || (!isVersionString(v) && !v.startsWith('claude-'))
+}
+
+module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteFrontmatterModelLine, rewriteSignatureLine, isVersionString, composeClaudeModelID, resolveAgentModel, looksLikeSuspectModelValue }

package/src/lib/fatal-error.js

@@ -0,0 +1,64 @@
+'use strict'
+
+const fs = require('node:fs')
+
+// fatal-error.js — global backstop for errors that escape every commander
+// action (sync or async, since npm/bin/trackfw drives the program via
+// parseAsync()). Installed ONCE at the entrypoint, never per-command:
+// the real leak pattern (REQ-2026-08-16-erro-nao-tratado-no-cli-node-vaza-
+// stack-trace-caminhos-absolutos-e-versao-do-runtime) was per-command —
+// commands that catch internally (e.g. `roadmap move`) already print a
+// clean message via console.error + process.exitCode, but any command that
+// doesn't catch let Node's own uncaught-exception/unhandled-rejection
+// printer dump the full stack, absolute install path and runtime version.
+// A single handler at the entrypoint closes every one of those gaps at
+// once instead of relying on every future command remembering a try/catch.
+//
+// TRACKFW_DEBUG=1 restores the full stack — this must never blind someone
+// who genuinely needs to debug a crash.
+//
+// Writes with fs.writeSync(2, ...) — NOT process.stderr.write() — on
+// purpose: installGlobalHandlers() below calls process.exit() right after
+// this returns, and when stderr is a pipe (exactly what every spawnSync-
+// based test in this repo uses, and what a piped CI log is) Node's stream
+// writes are asynchronous; process.exit() can drop a still-pending write
+// before the OS ever sees it, silently eating the message (failure mode
+// #2 in the REQ: "engolir a mensagem" — worse than the leak this handler
+// exists to fix). fs.writeSync is a raw, synchronous syscall — it cannot
+// race process.exit().
+function reportFatalError(err) {
+  // TRACKFW_DEBUG=1: print the full stack (its first line already is
+  // "Error: <message>", so this is the debug-only superset of the clean
+  // path below, not a duplicate of it).
+  if (process.env.TRACKFW_DEBUG === '1' && err && err.stack) {
+    fs.writeSync(2, `${err.stack}\n`)
+    return
+  }
+  const message = err && err.message !== undefined ? err.message : String(err)
+  fs.writeSync(2, `Error: ${message}\n`)
+}
+
+// installGlobalHandlers — defense in depth beyond the parseAsync().catch()
+// in bin/trackfw. Covers errors that reach the process outside that single
+// promise chain (e.g. a rejection from a detached/floating promise started
+// by a command, or a genuine uncaughtException). Per Node's own contract,
+// once a listener is attached Node no longer prints its default trace and
+// no longer auto-exits — the listener owns both the message and the exit.
+// Both listeners call process.exit() immediately after reportFatalError()
+// returns — safe here specifically because reportFatalError writes
+// synchronously (see comment above); process.exitCode (which waits for the
+// event loop to drain) would be wrong here regardless, since long-running
+// commands (e.g. `serve`) hold the loop open and the process would hang
+// instead of exiting on a genuinely fatal error.
+function installGlobalHandlers() {
+  process.on('unhandledRejection', (err) => {
+    reportFatalError(err)
+    process.exit(1)
+  })
+  process.on('uncaughtException', (err) => {
+    reportFatalError(err)
+    process.exit(1)
+  })
+}
+
+module.exports = { reportFatalError, installGlobalHandlers }