trackfw 7.2.0 → 7.4.0

package/src/commands/context.js

@@ -4,7 +4,7 @@ const { Command } = require('commander')
 const fs = require('fs')
 const path = require('path')
 const config = require('../config')
-const { validate } = require('../validator')
+const { validate, resolveAgentNamespaces, resolveReqFiles } = require('../validator')
 
 /**
  * extractFrontmatterField — extrai valor de campo YAML dentro de bloco --- ... ---.
@@ -85,11 +85,37 @@ function collectEntries(dir, type, state) {
   return entries
 }
 
+/**
+ * collectReqEntries — entradas de REQ para o `context`, derivadas do ponto único de leitura
+ * (resolveReqFiles). O `state` sai do nome da pasta-pai quando ela é um estado legado; em layout
+ * flat ou no canônico req_dir/<agente>/*.md não há estado (invariante D1: REQ não tem estado).
+ * @param {object} cfg
+ * @returns {Array<{type:string,file:string,status:string,state?:string}>}
+ */
+function collectReqEntries(cfg) {
+  const STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
+  const entries = []
+  for (const full of resolveReqFiles(cfg)) {
+    let content = ''
+    try { content = fs.readFileSync(full, 'utf8') } catch (_) {}
+    const parent = path.basename(path.dirname(full))
+    const state = STATES.includes(parent) ? parent : ''
+    let status = extractFrontmatterField(content, 'status')
+    if (!status) status = extractInlineStatus(content)
+    if (!status) status = state || 'unknown'
+    const entry = { type: 'REQ', file: path.basename(full), status }
+    if (state) entry.state = state
+    entries.push(entry)
+  }
+  return entries
+}
+
 /**
  * getContext — coleta governança e imprime em md ou json.
  * @param {string} format - 'md' | 'json'
+ * @returns {Promise<void>}
  */
-function getContext(format) {
+async function getContext(format) {
   const cfg = config.load()
 
   // ADRs
@@ -98,41 +124,15 @@ function getContext(format) {
     adrs.push(...collectEntries(adrDir, 'ADR'))
   }
 
-  // REQs
-  const reqs = []
-  const reqDir = cfg.reqDir || cfg.req_dir || 'docs/req'
-  const reqNamespacing = cfg.roadmapNamespacing || cfg.roadmap_namespacing || ''
-  if (reqNamespacing === 'by_agent') {
-    const STATES = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
-    let agents = cfg.agents || []
-    if (!agents.length) {
-      try {
-        agents = fs.readdirSync(reqDir).filter(f => {
-          try { return fs.statSync(path.join(reqDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) {}
-    }
-    for (const agent of agents) {
-      for (const state of STATES) {
-        reqs.push(...collectEntries(path.join(reqDir, agent, state), 'REQ', state))
-      }
-    }
-  } else {
-    reqs.push(...collectEntries(reqDir, 'REQ'))
-  }
+  // REQs — pelo PONTO ÚNICO de leitura (ADR-2026-09-03, D3/D4). Antes, `context` montava a própria
+  // árvore (flat, ou <agente>/<estado>/ em by_agent) e não enxergava o layout canônico <agente>/*.md.
+  const reqs = collectReqEntries(cfg)
 
   // Roadmaps
   const roadmaps = []
   const states = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
   if (cfg.roadmapNamespacing === 'by_agent') {
-    let agents = cfg.agents || []
-    if (agents.length === 0) {
-      try {
-        agents = fs.readdirSync(cfg.roadmapDir).filter(f => {
-          try { return fs.statSync(path.join(cfg.roadmapDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) { agents = [] }
-    }
+    const agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
     for (const agent of agents) {
       for (const state of states) {
         const dir = path.join(cfg.roadmapDir, agent, state)
@@ -147,7 +147,7 @@ function getContext(format) {
   }
 
   // Validate
-  const { violations, warnings } = validate()
+  const { violations, warnings } = await validate()
 
   // Score
   let score = 0
@@ -202,8 +202,14 @@ module.exports = (function () {
   cmd
     .description('Print governance context for LLM consumption')
     .option('--format <fmt>', 'Output format: md or json', 'md')
-    .action((opts) => {
-      getContext(opts.format)
-    })
+    // Retorna a Promise: o bin roda parseAsync() e só assim uma rejeição chega
+    // ao .catch(reportFatalError) com exit code 1 em vez de virar unhandled
+    // rejection (ML-1A, ROADMAP-2026-09-02-context-do-cli-node-aguarda-validate).
+    .action((opts) => getContext(opts.format))
   return cmd
 })()
+
+// Exposto para teste: o teste de context em by_agent duplicava a lógica de coleta e, por isso,
+// continuava verde mesmo quando a produção mudava (asserção sobre uma CÓPIA). Anexar a função ao
+// Command exportado é o menor caminho para o teste exercitar o código de produção de fato.
+module.exports.collectReqEntries = collectReqEntries

package/src/commands/discover.js

@@ -302,24 +302,72 @@ function installLefthook(rootDir) {
   }
 }
 
-function writeCIWorkflow(rootDir) {
-  const workflowsDir = path.join(rootDir, '.github', 'workflows');
-  if (!isDir(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
-  const dest = path.join(workflowsDir, 'trackfw-validate.yml');
-  if (isFile(dest)) return; // idempotente
-  const content = `name: trackfw validate
+// DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH is the canonical relative path of the second,
+// independent CI workflow trackfw writes — the one `trackfw discover --init` generates
+// via installGates, distinct from GITHUB_ACTIONS_WORKFLOW_PATH (trackfw-gate.yml,
+// written by init/update). Both files can coexist in the same project
+// (ADR-2026-08-28). Exported so scaffold_doctor.js can compare against it by path.
+const DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH = '.github/workflows/trackfw-validate.yml';
+
+// buildDiscoverGitHubActionsWorkflowContent returns the template content trackfw writes
+// to DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH. Mirrors
+// generators.BuildDiscoverGitHubActionsWorkflowContent in
+// internal/generators/scaffold_doctor.go (Go, canonical source of truth) byte-for-byte
+// for the same version.
+//
+// NOT version-independent (ADR-2026-08-28, REQ-2026-08-28 AC6/AC7): the `go install
+// .../cmd/trackfw@vX.Y.Z` step pins the second install mechanism (`go install ...@latest`)
+// to the version of npm/package.json — the version of the CLI that generated/updated the
+// project — mirroring the install.sh pin already applied to
+// buildGitHubActionsWorkflowContent (trackfw-gate.yml) in generators/init.js. Never
+// hardcoded: read lazily to avoid a circular require at module load time.
+//
+// Job id is `governance-go-install` (ML-1A, ROADMAP-2026-09-01) — was `governance`,
+// colliding with buildGitHubActionsWorkflowContent's job id (trackfw-gate.yml,
+// generators/init.js). See that function's doc comment for the full rationale; named
+// after the install mechanism (`go install`), not the workflow file.
+function buildDiscoverGitHubActionsWorkflowContent() {
+  const { version } = require('../../package.json');
+  return `name: trackfw validate
 on: [push, pull_request]
 jobs:
-  governance:
+  governance-go-install:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
           go-version: "1.22"
-      - run: go install github.com/kgsaran/trackfw/cmd/trackfw@latest
+      - run: go install github.com/kgsaran/trackfw/cmd/trackfw@v${version}
       - run: trackfw validate
 `;
+}
+
+function writeCIWorkflow(rootDir) {
+  const workflowsDir = path.join(rootDir, '.github', 'workflows');
+  if (!isDir(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
+  const dest = path.join(workflowsDir, 'trackfw-validate.yml');
+  // Uses fs.lstatSync directly, NOT the isFile helper (fs.statSync, follows
+  // symlinks): a DANGLING symlink at dest resolves to "does not exist" under
+  // fs.statSync, so the idempotency guard below would not fire, and
+  // fs.writeFileSync would then follow the link and CREATE the workflow
+  // template at whatever path outside the project the symlink points to. A
+  // symlink here — live or dangling — is treated as "already present" so
+  // this function never writes through it; it refuses loudly instead of
+  // silently creating a file somewhere the caller never asked for.
+  let info
+  try {
+    info = fs.lstatSync(dest)
+  } catch (e) {
+    info = null
+  }
+  if (info) {
+    if (info.isSymbolicLink()) {
+      console.error(`aviso: ${DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH} é um symlink; trackfw discover não escreve através de symlinks — arquivo não foi tocado`)
+    }
+    return; // idempotente — não sobrescreve (nem segue o link)
+  }
+  const content = buildDiscoverGitHubActionsWorkflowContent();
   fs.writeFileSync(dest, content, 'utf8');
 }
 
@@ -551,19 +599,20 @@ function writeCIWorkflowForce(rootDir) {
   const workflowsDir = path.join(rootDir, '.github', 'workflows');
   if (!isDir(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
   const dest = path.join(workflowsDir, 'trackfw-validate.yml');
-  const content = `name: trackfw validate
-on: [push, pull_request]
-jobs:
-  governance:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
-        with:
-          go-version: "1.22"
-      - run: go install github.com/kgsaran/trackfw/cmd/trackfw@latest
-      - run: trackfw validate
-`;
+  // Same symlink guard as writeCIWorkflow above: "force" means "overwrite
+  // an existing REGULAR file unconditionally", not "follow whatever this
+  // path resolves to". A symlink here — live or dangling — is refused, not
+  // followed.
+  try {
+    const info = fs.lstatSync(dest)
+    if (info.isSymbolicLink()) {
+      console.error(`aviso: ${DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH} é um symlink; trackfw discover não escreve através de symlinks — arquivo não foi tocado`)
+      return;
+    }
+  } catch (e) {
+    // does not exist — fine, this is the "force create" case
+  }
+  const content = buildDiscoverGitHubActionsWorkflowContent();
   fs.writeFileSync(dest, content, 'utf8');
 }
 
@@ -575,3 +624,5 @@ module.exports.writeValidateScript = writeValidateScript;
 module.exports.writeCIWorkflow = writeCIWorkflow;
 module.exports.writeCIWorkflowForce = writeCIWorkflowForce;
 module.exports.detectTestFramework = detectTestFramework;
+module.exports.buildDiscoverGitHubActionsWorkflowContent = buildDiscoverGitHubActionsWorkflowContent;
+module.exports.DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH = DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH;

package/src/commands/doctor.js

@@ -1,17 +1,38 @@
 'use strict'
 
 const { Command } = require('commander')
-const { runDoctor, UNREGISTERED_WRITE, HAND_MODIFIED, UNKNOWN_CONTENT } = require('../integrations/doctor')
+const {
+  runDoctor,
+  UNREGISTERED_WRITE,
+  HAND_MODIFIED,
+  UNKNOWN_CONTENT,
+  REQUIRED_STATUS_CHECKS_MISSING,
+  ENFORCE_ADMINS_DISABLED,
+  HOOKS_PATH_NEUTRALIZED,
+  NOT_EVALUATED,
+} = require('../integrations/doctor')
+const { runScaffoldDoctor, SCAFFOLD_DIVERGENT, SCAFFOLD_MISSING, SCAFFOLD_WRONG_MODE } = require('../integrations/scaffold_doctor')
+const { runDoctorRemote } = require('../integrations/doctor_remote')
 const projectConfig = require('../config')
 
 function printReport(findings) {
   if (findings.length === 0) {
-    return 'trackfw doctor: no mismatches found -- disk matches the manifest for every catalog-managed artifact.'
+    return 'trackfw doctor: no mismatches found -- disk matches the manifest for every catalog-managed artifact and all scaffold templates.'
   }
   const unregistered = findings.filter(finding => finding.finding === UNREGISTERED_WRITE).length
   const handModified = findings.filter(finding => finding.finding === HAND_MODIFIED).length
   const unknownContent = findings.filter(finding => finding.finding === UNKNOWN_CONTENT).length
-  const lines = [`trackfw doctor: ${findings.length} finding(s) -- ${unregistered} unregistered-write, ${handModified} hand-modified, ${unknownContent} unknown-content`, '']
+  const scaffoldDivergent = findings.filter(finding => finding.finding === SCAFFOLD_DIVERGENT).length
+  const scaffoldMissing = findings.filter(finding => finding.finding === SCAFFOLD_MISSING).length
+  const scaffoldWrongMode = findings.filter(finding => finding.finding === SCAFFOLD_WRONG_MODE).length
+  const requiredChecksMissing = findings.filter(finding => finding.finding === REQUIRED_STATUS_CHECKS_MISSING).length
+  const enforceAdminsDisabled = findings.filter(finding => finding.finding === ENFORCE_ADMINS_DISABLED).length
+  const hooksPathNeutralized = findings.filter(finding => finding.finding === HOOKS_PATH_NEUTRALIZED).length
+  const notEvaluated = findings.filter(finding => finding.finding === NOT_EVALUATED).length
+  const lines = [
+    `trackfw doctor: ${findings.length} finding(s) -- ${unregistered} unregistered-write, ${handModified} hand-modified, ${unknownContent} unknown-content, ${scaffoldDivergent} scaffold-divergent, ${scaffoldMissing} scaffold-missing, ${scaffoldWrongMode} scaffold-wrong-mode, ${requiredChecksMissing} required-status-checks-missing, ${enforceAdminsDisabled} enforce-admins-disabled, ${hooksPathNeutralized} hooks-path-neutralized, ${notEvaluated} not-evaluated`,
+    '',
+  ]
   for (const finding of findings) {
     lines.push(`[${finding.finding}] ${finding.destination}`, `  remedy: ${finding.remedy}`, '')
   }
@@ -21,8 +42,20 @@ function printReport(findings) {
 const cmd = new Command('doctor')
 cmd.description('Detect artifacts on disk missing from the manifest, distinguishing hand-modified artifacts from unknown content')
 cmd.option('--json', 'Emit findings as a JSON array instead of the text report')
+cmd.option('--remote', 'Also check GitHub branch protection (required_status_checks, enforce_admins) and local core.hooksPath neutralization. Requires network + a GitHub credential with admin access; absence of either is reported as not-evaluated, never as a pass (ADR-2026-09-02).')
 cmd.action(async options => {
-  const findings = runDoctor({ agentModels: projectConfig.load().agentModels || {} })
+  const projectRoot = process.cwd()
+  const catalogFindings = runDoctor({ agentModels: projectConfig.load().agentModels || {} })
+  // Scaffold coverage (ADR-2026-08-27): compare scaffold artifacts on disk against
+  // the templates the current binary would generate, using the project's own
+  // trackfw.yaml. No manifest entry is written or read (AC3).
+  const scaffoldFindings = runScaffoldDoctor(projectRoot)
+  let findings = [...catalogFindings, ...scaffoldFindings]
+  // Remote modality (ADR-2026-09-02, ML-3A): opt-in only — never runs without --remote, so
+  // doctor's offline default is unchanged.
+  if (options.remote) {
+    findings = [...findings, ...runDoctorRemote({ configForge: projectConfig.load().forge || '', repoDir: projectRoot })]
+  }
   if (options.json) {
     process.stdout.write(`${JSON.stringify(findings, null, 2)}\n`)
     return

package/src/commands/index.js

@@ -57,6 +57,7 @@ function createProgram() {
   program.addCommand(require('./commit'))
   program.addCommand(require('./push'))
   program.addCommand(require('./doctor'))
+  program.addCommand(require('./audit-surface'))
 
   const { createServeCommand } = require('./serve')
   program.addCommand(createServeCommand())

package/src/commands/init.js

@@ -5,6 +5,7 @@ const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { resolveIdentityPreset, identityFileExists } = identityWizard
 const { resolveScope } = require('./integrations')
+const { homedir } = require('../homedir')
 
 const cmd = new Command('init')
 cmd.description(t('init.description'))
@@ -16,7 +17,7 @@ cmd.action(async (options, command) => {
   const path = require('path')
   const generators = require('../generators/init')
 
-  const home = os.homedir()
+  const home = homedir()
 
   // A validação e persistência da flag acontecem incondicionalmente, acima
   // do early-return não-TTY abaixo — é isso que faz um --identity-preset

package/src/commands/integrations.js

@@ -10,6 +10,7 @@ const identityWizard = require('./identity-wizard')
 const { t } = require('../i18n')
 const { createThirdPartyCommand } = require('./thirdparty')
 const configModule = require('../config')
+const { homedir } = require('../homedir')
 
 const csv = value => String(value).split(',').map(entry => entry.trim()).filter(Boolean)
 const collect = (value, previous) => previous.concat(value)
@@ -179,7 +180,7 @@ function createLifecycleCommand(kind) {
       let presetChanged = false
       if (mutation && kind === 'agents') {
         presetChanged = cmd.getOptionValueSource('identityPreset') === 'cli'
-        if (presetChanged) identityWizard.applyIdentityPresetFlag(os.homedir(), options.identityPreset, operation)
+        if (presetChanged) identityWizard.applyIdentityPresetFlag(homedir(), options.identityPreset, operation)
       }
 
       if (mutation && (!options.targets || !options.targets.length)) {
@@ -197,7 +198,7 @@ function createLifecycleCommand(kind) {
       // planos abaixo. Espelha
       // internal/commands/integrations_flags.go:executeIntegrationMutation.
       if (mutation && kind === 'agents' && !presetChanged) {
-        const homeRoot = os.homedir()
+        const homeRoot = homedir()
         const identityExists = identityWizard.identityFileExists(homeRoot)
         const isTTY = Boolean(process.stdin.isTTY)
         if (identityWizard.shouldPromptIdentity(kind, isTTY, identityExists, forceIdentity)) {
@@ -221,7 +222,9 @@ function createLifecycleCommand(kind) {
         }
       }
 
-      options.agentModels = configModule.load().agentModels || {}
+      const { models: resolvedModels, warning: modelsWarning } = configModule.resolveAgentModels(options.scope, homedir(), process.cwd())
+      if (modelsWarning) process.stderr.write(modelsWarning + '\n')
+      options.agentModels = resolvedModels
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })
@@ -250,7 +253,22 @@ function createAgentModelsCommand() {
   const cmd = new Command('models')
     .description('Show the resolved model each agent uses per target')
   cmd.action(() => {
-    const agentModels = configModule.load().agentModels || {}
+    // AC5 + AC11: read agent_models from the global config (~/.trackfw/trackfw.yaml),
+    // not from the cwd singleton. Show origin before the table.
+    const { models: agentModels, source: modelsSource } = configModule.loadGlobalAgentModels(homedir(), process.cwd())
+
+    // Source line (AC5): show origin before the table; advisory to stderr when not resolved.
+    const sourceLines = {
+      global: 'source: ~/.trackfw/trackfw.yaml',
+      none: 'source: não configurado',
+      project_only: 'source: trackfw.yaml do projeto (não vale para escopo global)',
+      global_malformed: 'source: arquivo global malformado',
+    }
+    const sourceLine = sourceLines[modelsSource] || sourceLines['none']
+    process.stdout.write(sourceLine + '\n')
+    if (modelsSource === 'none') process.stderr.write(configModule.GLOBAL_AGENT_MODELS_NONE_MESSAGE + '\n')
+    else if (modelsSource === 'project_only') process.stderr.write(configModule.GLOBAL_AGENT_MODELS_PROJECT_ONLY_MESSAGE + '\n')
+    else if (modelsSource === 'global_malformed') process.stderr.write(configModule.MALFORMED_GLOBAL_CONFIG_MESSAGE + '\n')
 
     // Warnings: emit once per suspect tier, sorted, to stderr.
     const suspectTiers = Object.keys(agentModels)

package/src/commands/req.js

@@ -4,6 +4,7 @@ const os = require('os')
 const { Command } = require('commander')
 const { listREQs, moveREQ } = require('../generators/req')
 const { t } = require('../i18n')
+const { homedir } = require('../homedir')
 
 const cmd = new Command('req')
 cmd.description(t('req.description'))
@@ -38,7 +39,7 @@ cmd.command('new <title>')
         default: 'local',
       })
       const adrDir = adrScope === 'global'
-        ? path.join(os.homedir(), '.trackfw', 'adr')
+        ? path.join(homedir(), '.trackfw', 'adr')
         : require('../config').load().adrDirs[0]
 
       // Perguntas dinâmicas por probe

package/src/commands/thirdparty.js

@@ -6,8 +6,11 @@
 // `trackfw skills third-party` (D1). See:
 // docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
 
+const os = require('os')
+
 const { Command } = require('commander')
 
+const configModule = require('../config')
 const identityStore = require('../identity')
 const { items: catalogItems } = require('../integrations/catalog')
 const { buildPlans, IntegrationManager } = require('../integrations')
@@ -16,6 +19,7 @@ const { checkMarkers, checksum: sha256hex } = require('../thirdparty/markers')
 const { quarantinePath, newQuarantineEntry, writeQuarantine, readQuarantine, decodeContent } = require('../thirdparty/quarantine')
 const { loadProvenance, verifyApproval, upsertProvenanceEntry } = require('../thirdparty/provenance')
 const { upsertThirdPartyReference, normalizeThirdPartyContent, resolveThirdPartySkillDestination } = require('../thirdparty/references')
+const { homedir } = require('../homedir')
 
 // api is the module.exports object itself, referenced internally via
 // `api.thirdPartyFetch(...)` so tests can substitute the network fetch by
@@ -186,13 +190,15 @@ async function executeThirdPartyInstall(kind, options) {
   // write happens (including the skill file below) — failing everything up
   // front avoids leaving a partial state (skill file written, no reference
   // injected) on a precondition failure.
+  const { models: resolvedAgentModels, warning: agentModelsWarning } = configModule.resolveAgentModels(scope, homedir(), projectRoot)
+  if (agentModelsWarning) process.stderr.write(agentModelsWarning + '\n')
   let identityConfig
   if (options.applyTo && options.applyTo.length) {
     identityConfig = identityStore.load(manager.roots.global)
     for (const agentID of options.applyTo) {
       if (!catalogItems('agents').some(item => item.id === agentID)) throw new Error(`unknown agent item "${agentID}"`)
       for (const rt of resolvedTargets) {
-        const agentPlans = buildPlans('agents', { targets: [rt.targetID], items: [agentID], scope, identity: identityConfig, projectRoot })
+        const agentPlans = buildPlans('agents', { targets: [rt.targetID], items: [agentID], scope, identity: identityConfig, projectRoot, agentModels: resolvedAgentModels })
         if (!agentPlans.length) throw new Error(`target ${rt.targetID} has no supported agents surface for item "${agentID}"`)
         const inspection = manager.inspect([agentPlans[0]])[0]
         // ADR imprecision found and resolved here (reported, not silently
@@ -333,7 +339,7 @@ async function executeThirdPartyInstall(kind, options) {
         // immediately — not only on the next `agents update`. buildPlans
         // picks up the registry entry just written via
         // applyThirdPartyReferences (../integrations/index.js).
-        const agentPlans = buildPlans('agents', { targets: [rt.targetID], items: [agentID], scope, identity: identityConfig, projectRoot })
+        const agentPlans = buildPlans('agents', { targets: [rt.targetID], items: [agentID], scope, identity: identityConfig, projectRoot, agentModels: resolvedAgentModels })
         manager.update(agentPlans, {})
       }
     }

package/src/commands/update-harness.js

@@ -8,6 +8,7 @@ const projectConfig = require('../config')
 const { catalog, buildPlans, IntegrationManager, globalGroupPath } = require('../integrations')
 const { tildeify, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine')
 const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray, generateGlobalCredentialGuardScript, generateGlobalGitBranchGuardScript } = require('../generators/hooks')
+const { homedir } = require('../homedir')
 
 // `trackfw update harness` is the global counterpart to `trackfw update` —
 // see docs/cli-parity.md, "`trackfw update` vs `trackfw update harness`".
@@ -40,7 +41,7 @@ const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray, ge
 
 // claudeSkillContent — mirrors generators/init.js:installSkillsForce
 // (npm/src/generators/init.js:1242) byte-for-byte. Duplicated here, not
-// imported, because installSkillsForce() bakes os.homedir() internally with
+// imported, because installSkillsForce() bakes homedir() internally with
 // an unconditional overwrite and no dry-run mode — it cannot be reused
 // without either mutating on --dry-run or forking its signature. Reported
 // as a follow-up cleanup opportunity in the ML-6C handoff report.
@@ -758,7 +759,9 @@ function catalogBundleTarget(toolId, kind, homeRoot, identityConfig, { dryRun, i
   let displayPath = `~/.${toolId}`
   try {
     displayPath = globalGroupPath(toolId, kind)
-    const plans = buildPlans(kind, { targets: [toolId], scope: 'global', identity: identityConfig, agentModels: projectConfig.load().agentModels || {} })
+    const { models: harnessAgentModels, warning: harnessWarnMsg } = projectConfig.resolveAgentModels('global', homeRoot, process.cwd())
+    if (harnessWarnMsg) process.stderr.write(harnessWarnMsg + '\n')
+    const plans = buildPlans(kind, { targets: [toolId], scope: 'global', identity: identityConfig, agentModels: harnessAgentModels })
     if (!plans.length) return { id, state: 'missing', path: displayPath }
 
     const manager = new IntegrationManager({ homeRoot })
@@ -878,7 +881,7 @@ function run(options) {
     process.exit(1)
   }
 
-  const homeRoot = os.homedir()
+  const homeRoot = homedir()
   const dryRun = Boolean(options.dryRun)
   const installMissing = Boolean(options.installMissing)