forjajs 5.3.0 → 5.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -13,6 +13,38 @@ GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — v
13
13
 
14
14
  ---
15
15
 
16
+ ## [5.3.1] — 2026-11-16 — Windows funcional
17
+
18
+ ### O que melhorou
19
+
20
+ - **`llm:run`, `llm:doctor` e `eval:agents` funcionam no Windows.** O Forja encontra e executa
21
+ os CLIs de agente instalados pelo npm (`codex.cmd`, `claude.cmd`, `gemini.cmd`) sem WSL.
22
+ O timeout derruba a árvore inteira do processo — um agente estourado para de queimar token.
23
+ - **`forja simulate` funciona no Windows.** O worktree Git é criado, o comando roda e a
24
+ limpeza fecha sem EPERM. O npm é resolvido pelo shim `.cmd` correto.
25
+ - **`spec:trace` conta critérios em checkouts CRLF.** Projetos clonados no Windows não
26
+ reportam mais 0/0 critérios por causa do separador de linha.
27
+ - **O CI bloqueia em toda célula.** Windows deixou de ser tolerância informacional e agora
28
+ segura o merge como ubuntu e macOS. Regressões de plataforma não chegam ao release.
29
+
30
+ ### Corrigido
31
+
32
+ - Spawn de `.cmd`/`.bat` sem `shell: true` (CVE-2024-27980) resolvido por launcher próprio
33
+ com quoting de cmd.exe testado contra injeção de argumentos (#86).
34
+ - `resolveCommand` prefere extensão executável (`.cmd`/`.exe`) sobre scripts sem extensão
35
+ que o `where` lista primeiro (#86).
36
+ - `sandboxEnvironment` inclui `APPDATA`, `LOCALAPPDATA`, `COMSPEC`, `PATHEXT` — npm e git
37
+ funcionam dentro do worktree sem herdar secrets (#86).
38
+ - Caminhos 8.3 (`RUNNER~1`) canonicalizados com `realpathSync` antes de comparação (#86).
39
+ - `parseCriteria` aceita CRLF (`\r?\n`) no checklist de specs (#86).
40
+
41
+ ### Adicionado
42
+
43
+ - `lib/exec.ts`: módulo portável de subprocesso — `resolveCommand`, `spawnAgent`, `runShell`,
44
+ `killTree`. Sem dependência nova. 14 testes incluindo roundtrip de argumentos hostis (#86).
45
+
46
+ ---
47
+
16
48
  ## [5.3.0] — 2026-11-14 — Supervisão, execução vinculada e qualidade verificável
17
49
 
18
50
  ### O que melhorou
package/README.md CHANGED
@@ -146,9 +146,9 @@ process followed?", the answer is a file, not a promise.
146
146
  command documentation and a versioned coverage floor. Upgrading from 5.1.0 also includes session
147
147
  checkpoints, acceptance-criteria tracing and agent evaluations documented in the changelog.
148
148
 
149
- Windows still has open agent-runtime, worktree simulation and `spec:trace` journey limitations;
150
- see the [quality-gates inventory](specs/v6-quality-gates/spec.md). Full Windows portability is not
151
- claimed. Details and upgrade notes: [CHANGELOG](CHANGELOG.md).
149
+ Windows is fully supported since 5.3.1: `llm:run`, `llm:doctor`, `eval:agents`, `simulate` and
150
+ `spec:trace` work without WSL. The CI matrix blocks on all three OSes.
151
+ Details and upgrade notes: [CHANGELOG](CHANGELOG.md).
152
152
 
153
153
  ## ⚡ Quick start
154
154
 
@@ -462,6 +462,21 @@ output, code, and ADRs are readable regardless of language.
462
462
  The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
463
463
  below either closes a framework frontier with a gate, or carries that pattern into generated projects.
464
464
 
465
+ **Shipped** (v5.3.0 — Supervised execution)
466
+
467
+ - [x] **Read-only supervision dashboard** — overview, acceptance-criteria traceability, observed
468
+ costs, gates and operations share the server's capability registry; optional, token-gated,
469
+ runs from the checkout (CLI-first install unchanged).
470
+ - [x] **Context-backed planning & linked execution** — tasks, handoffs, memory and budgets connect
471
+ to persisted, reviewable proposals; plan review does not authorize execution; completion requires
472
+ independent checks. Default server remains read-only.
473
+ - [x] **Host-owned authorization** — registered capability categories determine policy, not
474
+ request-supplied categories; custom registrations declare `CapabilityRegistration.categories`.
475
+ - [x] **Paused-sprint guards** — linked runs reject execute/resume while the sprint is paused;
476
+ cancellation and terminal reconciliation remain available.
477
+ - [x] **Compact context & measurable quality** — FTS5 snippets, incremental memory indexing,
478
+ generated command documentation and a versioned coverage floor.
479
+
465
480
  **Shipped** (v3.0.0 — Engineering Control Plane, ADR-0078)
466
481
 
467
482
  - [x] **Engineering Graph** — ADRs/SPECs as first-class, queryable nodes (`adr:list/show/impact/graph`),
package/README.pt-BR.md CHANGED
@@ -113,9 +113,9 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
113
113
  documentação de comandos gerada e piso de cobertura versionado. Quem atualiza da 5.1.0 também
114
114
  recebe checkpoints de sessão, rastreabilidade de critérios e avaliação de agentes descritos no changelog.
115
115
 
116
- O Windows ainda tem limitações abertas no runtime de agentes, na simulação por worktree e na
117
- jornada `spec:trace`; veja o [inventário de qualidade](specs/v6-quality-gates/spec.md). Não há
118
- promessa de portabilidade completa. Detalhes e notas de atualização: [CHANGELOG](CHANGELOG.md).
116
+ O Windows é suportado desde a 5.3.1: `llm:run`, `llm:doctor`, `eval:agents`, `simulate` e
117
+ `spec:trace` funcionam sem WSL. O CI bloqueia nos três SOs.
118
+ Detalhes e notas de atualização: [CHANGELOG](CHANGELOG.md).
119
119
 
120
120
  ## ⚡ Quick start
121
121
 
@@ -381,6 +381,21 @@ O fio condutor: **converter conhecimento que vive em convenção em invariante e
381
381
  item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
382
382
  gerados.
383
383
 
384
+ **Entregue** (v5.3.0 — Execução supervisionada)
385
+
386
+ - [x] **Painel de supervisão somente leitura** — visão, rastreabilidade de critérios, custos
387
+ observados, gates e operação usam o registro de capacidades do servidor; opcional, com token,
388
+ roda pelo checkout (instalação CLI-first inalterada).
389
+ - [x] **Planejamento com contexto e execução vinculada** — tarefas, handoffs, memória e orçamento
390
+ conectam-se a propostas persistidas e revisáveis; revisar plano não autoriza execução; concluir
391
+ exige checks independentes. Servidor padrão continua somente leitura.
392
+ - [x] **Autorização pertence ao host** — categorias registradas da capacidade determinam a política,
393
+ não as categorias da requisição; registros próprios declaram `CapabilityRegistration.categories`.
394
+ - [x] **Guardas de sprint pausada** — runs vinculados recusam execute/resume com a sprint pausada;
395
+ cancelamento e reconciliação terminal permanecem disponíveis.
396
+ - [x] **Contexto compacto e qualidade mensurável** — trechos FTS5, indexação incremental de memória,
397
+ documentação de comandos gerada e piso de cobertura versionado.
398
+
384
399
  **Entregue** (v3.0.0 — Engineering Control Plane, ADR-0078)
385
400
 
386
401
  - [x] **Engineering Graph** — ADRs/SPECs como nós de primeira classe consultáveis
@@ -12,6 +12,7 @@ import os from 'node:os';
12
12
  import path from 'node:path';
13
13
  import { spawnSync } from 'node:child_process';
14
14
  import { traceSpecs } from './spec-trace.js';
15
+ import { resolveCommand, runShell, quoteCmdArg } from './exec.js';
15
16
  const CHECK_TYPES = new Set(['file', 'answer', 'ran', 'criterion', 'command', 'unchanged']);
16
17
  export function validateCase(c, source = 'caso') {
17
18
  const fail = (msg) => { throw new Error(`${source}: ${msg}`); };
@@ -153,12 +154,20 @@ export function parseCodexJson(stdout) {
153
154
  }
154
155
  function timed(bin, args, ctx) {
155
156
  const t0 = Date.now();
156
- const r = spawnSync(bin, args, { cwd: ctx.projectDir, env: ctx.env, encoding: 'utf8', timeout: ctx.timeoutMs, input: '', maxBuffer: 256 * 1024 * 1024 });
157
+ const resolved = resolveCommand(bin) ?? bin;
158
+ const isCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
159
+ const r = isCmd
160
+ ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${resolved}" ${args.map(quoteCmdArg).join(' ')}"`], { cwd: ctx.projectDir, env: ctx.env, encoding: 'utf8', timeout: ctx.timeoutMs, input: '', maxBuffer: 256 * 1024 * 1024, windowsVerbatimArguments: true })
161
+ : spawnSync(resolved, args, { cwd: ctx.projectDir, env: ctx.env, encoding: 'utf8', timeout: ctx.timeoutMs, input: '', maxBuffer: 256 * 1024 * 1024 });
157
162
  const timedOut = r.error && r.error.code === 'ETIMEDOUT';
158
163
  return { r, durationMs: Date.now() - t0, timedOut: Boolean(timedOut) };
159
164
  }
160
165
  function cliVersion(bin) {
161
- const r = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 15_000 });
166
+ const resolved = resolveCommand(bin) ?? bin;
167
+ const isCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
168
+ const r = isCmd
169
+ ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${resolved}" --version"`], { encoding: 'utf8', timeout: 15_000, windowsVerbatimArguments: true })
170
+ : spawnSync(resolved, ['--version'], { encoding: 'utf8', timeout: 15_000 });
162
171
  return r.status === 0 ? (r.stdout || '').trim().split('\n')[0] : null;
163
172
  }
164
173
  export const claudeAdapter = (bin = 'claude') => ({
@@ -222,7 +231,7 @@ export function grade(check, projectDir, run, before, env) {
222
231
  return c.tests.length ? res(true, c.tests.map((t) => `${t.file}:${t.line}`).join(', ')) : res(false, 'nenhum teste cita o critério');
223
232
  }
224
233
  case 'command': {
225
- const r = spawnSync('sh', ['-c', check.run], { cwd: projectDir, env, encoding: 'utf8', timeout: 120_000 });
234
+ const r = runShell(check.run, { cwd: projectDir, env, timeoutMs: 120_000 });
226
235
  const want = check.expectExit ?? 0;
227
236
  const tail = `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').slice(-2).join(' | ').slice(0, 200);
228
237
  return r.status === want ? res(true, `exit ${r.status}`) : res(false, `exit ${r.status} (esperado ${want}): ${tail}`);
@@ -240,10 +249,17 @@ export function grade(check, projectDir, run, before, env) {
240
249
  export function prepareProject(baseDir, name, forjaBin) {
241
250
  const bin = path.join(baseDir, 'bin');
242
251
  fs.mkdirSync(bin, { recursive: true });
243
- const shim = path.join(bin, 'forja');
244
- if (!fs.existsSync(shim)) {
245
- fs.writeFileSync(shim, `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} ${JSON.stringify(forjaBin)} "$@"\n`);
246
- fs.chmodSync(shim, 0o755);
252
+ if (process.platform === 'win32') {
253
+ const shim = path.join(bin, 'forja.cmd');
254
+ if (!fs.existsSync(shim))
255
+ fs.writeFileSync(shim, `@echo off\r\n"${process.execPath}" "${forjaBin}" %*\r\n`);
256
+ }
257
+ else {
258
+ const shim = path.join(bin, 'forja');
259
+ if (!fs.existsSync(shim)) {
260
+ fs.writeFileSync(shim, `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} ${JSON.stringify(forjaBin)} "$@"\n`);
261
+ fs.chmodSync(shim, 0o755);
262
+ }
247
263
  }
248
264
  const ws = path.join(baseDir, 'ws');
249
265
  const env = { ...process.env, FORJA_WORKSPACE: ws, PATH: `${bin}${path.delimiter}${process.env.PATH ?? ''}` };
@@ -0,0 +1,55 @@
1
+ /**
2
+ * lib/exec.ts — fronteira de subprocesso portável (SPEC-059).
3
+ *
4
+ * Resolve binários por plataforma (`where`/`which` + PATHEXT), spawnar `.cmd`/`.bat`
5
+ * sem `shell: true` (CVE-2024-27980), launcher de shell portável e kill de árvore.
6
+ * Sem dependência nova: o quoting de cmd.exe é ~30 linhas testadas exaustivamente.
7
+ *
8
+ * Precedente: `hasBinary()` em lib/project-wiring.ts:98.
9
+ */
10
+ import { type ChildProcess, type SpawnOptions, type SpawnSyncReturns } from 'node:child_process';
11
+ /**
12
+ * Resolve um binário para caminho absoluto, ou null se não encontrável.
13
+ * POSIX: `which`. Windows: `where` + PATHEXT (`.CMD;.BAT;.EXE;…`).
14
+ */
15
+ export declare function resolveCommand(bin: string): string | null;
16
+ /**
17
+ * Escapa um argumento para cmd.exe + parser MSVCRT do processo-filho.
18
+ *
19
+ * Estratégia (a mesma do cross-spawn, sem a dependência):
20
+ * 1. Quoting MSVCRT: envolve em `"`, escapa `"` como `\"`, dobra `\` antes de `"`.
21
+ * 2. Escapa metacaracteres do cmd.exe (`% ^ & | < > ( ) "`) com `^` — fora das aspas
22
+ * MSVCRT, o `^` é processado pelo parser do cmd.exe antes da expansão de variáveis.
23
+ *
24
+ * Limitação conhecida: `%VAR%` dentro de aspas ainda é expandido pelo cmd.exe se VAR
25
+ * existir no ambiente. Na prática, argumentos de agentes (prompts, flags) raramente
26
+ * contêm padrões `%VAR%` que casem com variáveis reais. O teste AC-2 usa variável
27
+ * inexistente, que o cmd.exe preserva literal.
28
+ */
29
+ export declare function quoteCmdArg(arg: string): string;
30
+ export interface SpawnAgentOptions extends SpawnOptions {
31
+ readonly timeoutMs?: number;
32
+ }
33
+ /**
34
+ * Spawna um executável de agente de forma portável.
35
+ * - Resolve via resolveCommand (where/which + PATHEXT).
36
+ * - `.cmd`/`.bat` → cmd.exe /d /s /c com quoting próprio (nunca shell: true).
37
+ * - Outros → spawn direto, shell: false.
38
+ * - detached: true em POSIX (process group para killTree); false em Windows.
39
+ */
40
+ export declare function spawnAgent(executable: string, args: readonly string[], opts?: SpawnAgentOptions): ChildProcess;
41
+ /**
42
+ * Launcher de shell portável para checks declarativos (`type: 'command'`).
43
+ * POSIX: `sh -c`. Windows: `%ComSpec% /d /s /c`.
44
+ */
45
+ export declare function runShell(command: string, opts?: {
46
+ cwd?: string;
47
+ env?: NodeJS.ProcessEnv;
48
+ timeoutMs?: number;
49
+ }): SpawnSyncReturns<string>;
50
+ /**
51
+ * Derruba a árvore de processos.
52
+ * POSIX: kill(-pid, SIGTERM) → grace → kill(-pid, SIGKILL).
53
+ * Windows: taskkill /pid <pid> /T /F (alcança netos de shim .cmd).
54
+ */
55
+ export declare function killTree(pid: number, graceMs?: number): void;
@@ -0,0 +1,141 @@
1
+ /**
2
+ * lib/exec.ts — fronteira de subprocesso portável (SPEC-059).
3
+ *
4
+ * Resolve binários por plataforma (`where`/`which` + PATHEXT), spawnar `.cmd`/`.bat`
5
+ * sem `shell: true` (CVE-2024-27980), launcher de shell portável e kill de árvore.
6
+ * Sem dependência nova: o quoting de cmd.exe é ~30 linhas testadas exaustivamente.
7
+ *
8
+ * Precedente: `hasBinary()` em lib/project-wiring.ts:98.
9
+ */
10
+ import { spawn, spawnSync } from 'node:child_process';
11
+ import path from 'node:path';
12
+ const IS_WIN = process.platform === 'win32';
13
+ /**
14
+ * Resolve um binário para caminho absoluto, ou null se não encontrável.
15
+ * POSIX: `which`. Windows: `where` + PATHEXT (`.CMD;.BAT;.EXE;…`).
16
+ */
17
+ export function resolveCommand(bin) {
18
+ if (path.isAbsolute(bin))
19
+ return bin;
20
+ const finder = IS_WIN ? 'where' : 'which';
21
+ const r = spawnSync(finder, [bin], { encoding: 'utf8', timeout: 5_000 });
22
+ if (r.status === 0 && r.stdout) {
23
+ const lines = r.stdout.trim().split(/\r?\n/).filter(Boolean);
24
+ if (IS_WIN) {
25
+ const exec = lines.find((l) => /\.(cmd|bat|exe|com)$/i.test(l));
26
+ if (exec)
27
+ return exec;
28
+ }
29
+ if (lines[0])
30
+ return lines[0];
31
+ }
32
+ if (IS_WIN) {
33
+ const exts = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
34
+ for (const ext of exts) {
35
+ const candidate = `${bin}${ext}`;
36
+ const probe = spawnSync('where', [candidate], { encoding: 'utf8', timeout: 5_000 });
37
+ if (probe.status === 0 && probe.stdout) {
38
+ const first = probe.stdout.trim().split(/\r?\n/)[0];
39
+ if (first)
40
+ return first;
41
+ }
42
+ }
43
+ }
44
+ return null;
45
+ }
46
+ /**
47
+ * Escapa um argumento para cmd.exe + parser MSVCRT do processo-filho.
48
+ *
49
+ * Estratégia (a mesma do cross-spawn, sem a dependência):
50
+ * 1. Quoting MSVCRT: envolve em `"`, escapa `"` como `\"`, dobra `\` antes de `"`.
51
+ * 2. Escapa metacaracteres do cmd.exe (`% ^ & | < > ( ) "`) com `^` — fora das aspas
52
+ * MSVCRT, o `^` é processado pelo parser do cmd.exe antes da expansão de variáveis.
53
+ *
54
+ * Limitação conhecida: `%VAR%` dentro de aspas ainda é expandido pelo cmd.exe se VAR
55
+ * existir no ambiente. Na prática, argumentos de agentes (prompts, flags) raramente
56
+ * contêm padrões `%VAR%` que casem com variáveis reais. O teste AC-2 usa variável
57
+ * inexistente, que o cmd.exe preserva literal.
58
+ */
59
+ export function quoteCmdArg(arg) {
60
+ if (arg.length === 0)
61
+ return '""';
62
+ let s = arg.replace(/(\\*)"/g, '$1$1\\"');
63
+ s = s.replace(/(\\*)$/, '$1$1');
64
+ s = `"${s}"`;
65
+ s = s.replace(/[()%!^"<>&|]/g, '^$&');
66
+ return s;
67
+ }
68
+ /**
69
+ * Spawna um executável de agente de forma portável.
70
+ * - Resolve via resolveCommand (where/which + PATHEXT).
71
+ * - `.cmd`/`.bat` → cmd.exe /d /s /c com quoting próprio (nunca shell: true).
72
+ * - Outros → spawn direto, shell: false.
73
+ * - detached: true em POSIX (process group para killTree); false em Windows.
74
+ */
75
+ export function spawnAgent(executable, args, opts = {}) {
76
+ const resolved = resolveCommand(executable) ?? executable;
77
+ const isCmd = IS_WIN && /\.(cmd|bat)$/i.test(resolved);
78
+ if (isCmd) {
79
+ const comspec = process.env.ComSpec ?? 'cmd.exe';
80
+ const commandLine = `"${resolved}" ${args.map(quoteCmdArg).join(' ')}`;
81
+ return spawn(comspec, ['/d', '/s', '/c', `"${commandLine}"`], {
82
+ ...opts,
83
+ shell: false,
84
+ detached: false,
85
+ windowsVerbatimArguments: true,
86
+ });
87
+ }
88
+ return spawn(resolved, [...args], {
89
+ ...opts,
90
+ shell: false,
91
+ detached: opts.detached ?? !IS_WIN,
92
+ });
93
+ }
94
+ /**
95
+ * Launcher de shell portável para checks declarativos (`type: 'command'`).
96
+ * POSIX: `sh -c`. Windows: `%ComSpec% /d /s /c`.
97
+ */
98
+ export function runShell(command, opts = {}) {
99
+ const shell = IS_WIN ? (process.env.ComSpec ?? 'cmd.exe') : 'sh';
100
+ const shellArgs = IS_WIN ? ['/d', '/s', '/c', command] : ['-c', command];
101
+ return spawnSync(shell, shellArgs, {
102
+ cwd: opts.cwd,
103
+ env: opts.env,
104
+ encoding: 'utf8',
105
+ timeout: opts.timeoutMs ?? 120_000,
106
+ });
107
+ }
108
+ /**
109
+ * Derruba a árvore de processos.
110
+ * POSIX: kill(-pid, SIGTERM) → grace → kill(-pid, SIGKILL).
111
+ * Windows: taskkill /pid <pid> /T /F (alcança netos de shim .cmd).
112
+ */
113
+ export function killTree(pid, graceMs = 3_000) {
114
+ if (IS_WIN) {
115
+ try {
116
+ spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { timeout: 10_000 });
117
+ }
118
+ catch { /* já morto */ }
119
+ return;
120
+ }
121
+ try {
122
+ process.kill(-pid, 'SIGTERM');
123
+ }
124
+ catch {
125
+ try {
126
+ process.kill(pid, 'SIGTERM');
127
+ }
128
+ catch { /* já morto */ }
129
+ }
130
+ setTimeout(() => {
131
+ try {
132
+ process.kill(-pid, 'SIGKILL');
133
+ }
134
+ catch {
135
+ try {
136
+ process.kill(pid, 'SIGKILL');
137
+ }
138
+ catch { /* já morto */ }
139
+ }
140
+ }, graceMs).unref();
141
+ }
@@ -22,7 +22,7 @@ const QUALIFIED = /\b(SPEC-\d+|[a-z0-9]+(?:-[a-z0-9]+)*)[\s#:(]+(AC-\d+(?:\s*(?:
22
22
  const AC_TOKEN = /\bAC-\d+\b/g;
23
23
  export function parseCriteria(specText) {
24
24
  const out = [];
25
- for (const line of specText.split('\n')) {
25
+ for (const line of specText.split(/\r?\n/)) {
26
26
  const m = line.match(AC_LINE);
27
27
  if (m && !out.some((c) => c.id === m[1]))
28
28
  out.push({ id: m[1], text: m[2].trim() });
@@ -3,10 +3,15 @@ import path from 'node:path';
3
3
  import { spawnSync } from 'node:child_process';
4
4
  import { graphDocumentId } from '../../graph/src/index.js';
5
5
  import { isPathWithinRoot } from '../../contracts/src/index.js';
6
+ import { resolveCommand, quoteCmdArg } from '../../../lib/exec.js';
6
7
  export class SpawnCommandRunner {
7
8
  run(command) {
8
9
  const started = Date.now();
9
- const result = spawnSync(command.executable, [...command.args], { cwd: command.cwd, env: sandboxEnvironment(command.env), encoding: 'utf8' });
10
+ const resolved = resolveCommand(command.executable) ?? command.executable;
11
+ const isCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
12
+ const result = isCmd
13
+ ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${resolved}" ${command.args.map(quoteCmdArg).join(' ')}"`], { cwd: command.cwd, env: sandboxEnvironment(command.env), encoding: 'utf8', windowsVerbatimArguments: true })
14
+ : spawnSync(resolved, [...command.args], { cwd: command.cwd, env: sandboxEnvironment(command.env), encoding: 'utf8' });
10
15
  return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: [result.stderr ?? '', result.error?.message ?? ''].filter(Boolean).join('\n'), durationMs: Date.now() - started };
11
16
  }
12
17
  }
@@ -56,7 +61,7 @@ function isIndexable(relative) {
56
61
  */
57
62
  function sandboxEnvironment(overrides) {
58
63
  const inherited = {};
59
- for (const key of ['PATH', 'NODE_PATH', 'SystemRoot', 'TMPDIR', 'TMP', 'TEMP', 'HOME', 'USERPROFILE']) {
64
+ for (const key of ['PATH', 'NODE_PATH', 'SystemRoot', 'TMPDIR', 'TMP', 'TEMP', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'COMSPEC', 'PATHEXT']) {
60
65
  const value = process.env[key];
61
66
  if (value !== undefined)
62
67
  inherited[key] = value;
@@ -113,10 +118,14 @@ export class GitWorktreeBackend {
113
118
  await this.options.patchApplier.revert(this.options.repositoryRoot, patch.stdout);
114
119
  }
115
120
  async reject(session) {
116
- await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'remove', '--force', session.root]);
121
+ const r = await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'remove', '--force', session.root]);
122
+ if (r.exitCode !== 0)
123
+ await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'prune']);
117
124
  }
118
125
  async destroy(session) {
119
- await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'remove', '--force', session.root]);
126
+ const r = await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'remove', '--force', session.root]);
127
+ if (r.exitCode !== 0)
128
+ await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'prune']);
120
129
  }
121
130
  async runGit(args) {
122
131
  return this.runner.run({ executable: 'git', args });
@@ -1,4 +1,4 @@
1
- import { spawn } from 'node:child_process';
1
+ import { spawnAgent, killTree } from '../../../lib/exec.js';
2
2
  export const LLM_PROFILE_VERSION = 1;
3
3
  export const DEFAULT_LLM_PROFILES = {
4
4
  version: LLM_PROFILE_VERSION,
@@ -41,7 +41,7 @@ export function buildLlmExecution(profile, prompt, options = {}) {
41
41
  if (profile.provider === 'codex')
42
42
  return {
43
43
  executable: profile.command,
44
- args: ['exec', ...base, '--sandbox', 'read-only', '-c', 'approval_policy="never"',
44
+ args: [...base, 'exec', '--sandbox', 'read-only', '-c', 'approval_policy="never"',
45
45
  ...(options.resume ? ['resume', '-c', 'sandbox_mode="read-only"', '-c', 'approval_policy="never"'] : []),
46
46
  ...(profile.model === 'default' ? [] : ['--model', profile.model]),
47
47
  ...(profile.reasoningEffort ? ['-c', `model_reasoning_effort="${profile.reasoningEffort}"`] : []),
@@ -85,9 +85,7 @@ export async function runLlm(execution, cwd, timeoutMs = 120_000) {
85
85
  settled = true;
86
86
  resolve({ ...result, durationMs: Date.now() - started });
87
87
  };
88
- // detached so the child leads its own process group: a negative pid targets the whole group,
89
- // reaching grandchildren the CLI tool itself spawned (not just the immediate child).
90
- const child = spawn(execution.executable, execution.args, { cwd, shell: false, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
88
+ const child = spawnAgent(execution.executable, execution.args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
91
89
  // A provider can close stdin early (e.g. invalid configuration). Its exit status is authoritative.
92
90
  child.stdin.on('error', () => { });
93
91
  child.stdin.end(execution.stdin);
@@ -95,28 +93,13 @@ export async function runLlm(execution, cwd, timeoutMs = 120_000) {
95
93
  child.stderr.setEncoding('utf8');
96
94
  child.stdout.on('data', (chunk) => { stdout += chunk; });
97
95
  child.stderr.on('data', (chunk) => { stderr += chunk; });
98
- const killGroup = (signal) => {
99
- if (child.pid === undefined)
100
- return;
101
- try {
102
- process.kill(-child.pid, signal);
103
- }
104
- catch {
105
- // no process group (platform didn't support detached, or it's already gone) — fall back to the child alone
106
- try {
107
- child.kill(signal);
108
- }
109
- catch { /* already dead */ }
110
- }
111
- };
112
- let killTimer;
113
96
  const timer = setTimeout(() => {
114
- killGroup('SIGTERM');
115
- killTimer = setTimeout(() => killGroup('SIGKILL'), SIGTERM_GRACE_MS);
97
+ if (child.pid !== undefined)
98
+ killTree(child.pid, SIGTERM_GRACE_MS);
116
99
  finish({ exitCode: 124, stdout, stderr, errorCode: 'TIMEOUT' });
117
100
  }, timeoutMs);
118
- child.on('error', (error) => { clearTimeout(timer); clearTimeout(killTimer); finish({ exitCode: 127, stdout, stderr: `${stderr}${error.message}`, errorCode: 'SPAWN_FAILED' }); });
119
- child.on('close', (code) => { clearTimeout(timer); clearTimeout(killTimer); finish({ exitCode: code ?? 1, stdout, stderr, ...(code === 0 ? {} : { errorCode: 'COMMAND_FAILED' }) }); });
101
+ child.on('error', (error) => { clearTimeout(timer); finish({ exitCode: 127, stdout, stderr: `${stderr}${error.message}`, errorCode: 'SPAWN_FAILED' }); });
102
+ child.on('close', (code) => { clearTimeout(timer); finish({ exitCode: code ?? 1, stdout, stderr, ...(code === 0 ? {} : { errorCode: 'COMMAND_FAILED' }) }); });
120
103
  });
121
104
  }
122
105
  function median(values) {
@@ -2,6 +2,7 @@
2
2
  import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { spawnSync } from 'node:child_process';
5
+ import { resolveCommand, quoteCmdArg } from '../lib/exec.js';
5
6
  import Database from 'better-sqlite3';
6
7
  import { createHash, randomUUID } from 'node:crypto';
7
8
  import { DEFAULT_LLM_PROFILES, buildLlmExecution, recommendProfile, runLlm, validateProfiles } from '../packages/llm/src/index.js';
@@ -16,6 +17,13 @@ import { normalizeClaudeResult } from '../lib/llm/claude-output.js';
16
17
  import { LlmSessionStore, RESUME_PROVIDERS, validSessionId } from '../lib/llm/session.js';
17
18
  import { normalizeGeminiResult, normalizeCursorResult } from '../lib/llm/json-output.js';
18
19
  import { prepareValidation, validateLlmResponse } from '../lib/llm/validation.js';
20
+ function probeSync(bin, args) {
21
+ const resolved = resolveCommand(bin) ?? bin;
22
+ const isCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
23
+ return isCmd
24
+ ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${resolved}" ${args.map(quoteCmdArg).join(' ')}"`], { encoding: 'utf8', timeout: 10_000, windowsVerbatimArguments: true })
25
+ : spawnSync(resolved, args, { encoding: 'utf8', timeout: 10_000 });
26
+ }
19
27
  const profilePath = () => path.join(getWorkspaceContextDir(), 'llm-profiles.json');
20
28
  function usage() {
21
29
  console.error('Uso: forja llm:<doctor|profiles:init|probe|recommend|run|eval>');
@@ -70,7 +78,8 @@ function doctor(name) {
70
78
  if (name && !configured[name])
71
79
  throw new Error(`Perfil não encontrado: ${name}`);
72
80
  const result = Object.entries(configured).filter(([profileName]) => name === undefined || profileName === name).map(([profileName, value]) => {
73
- const probe = spawnSync(value.command, ['--version'], { encoding: 'utf8', timeout: 10_000, shell: false });
81
+ const prefix = value.commandArgs ?? [];
82
+ const probe = probeSync(value.command, [...prefix, '--version']);
74
83
  const errorCode = probe.error?.code;
75
84
  const model = `${value.provider}:${value.model}`;
76
85
  const pricing = pricingInfo(model);
@@ -78,15 +87,15 @@ function doctor(name) {
78
87
  let compatible = null;
79
88
  let features;
80
89
  if (available && value.provider === 'codex') {
81
- const help = spawnSync(value.command, ['exec', '--help'], { encoding: 'utf8', timeout: 10_000, shell: false });
90
+ const help = probeSync(value.command, [...prefix, 'exec', '--help']);
82
91
  compatible = !help.error && help.status === 0 && ['--json', '--sandbox', '--config'].every((flag) => help.stdout.includes(flag));
83
- const resumeHelp = spawnSync(value.command, ['exec', 'resume', '--help'], { encoding: 'utf8', timeout: 10_000, shell: false });
92
+ const resumeHelp = probeSync(value.command, [...prefix, 'exec', 'resume', '--help']);
84
93
  features = { outputSchema: !help.error && help.status === 0 && help.stdout.includes('--output-schema'),
85
94
  resume: !resumeHelp.error && resumeHelp.status === 0 && ['--json', '--config'].every((flag) => resumeHelp.stdout.includes(flag)) };
86
95
  }
87
96
  else if (available && value.provider === 'claude') {
88
97
  // SPEC-050 — o `claude` CLI oferece --resume nativo; schema não (validação é local, Ajv).
89
- const help = spawnSync(value.command, ['--help'], { encoding: 'utf8', timeout: 10_000, shell: false });
98
+ const help = probeSync(value.command, [...prefix, '--help']);
90
99
  const helpOk = !help.error && help.status === 0;
91
100
  compatible = helpOk && ['--output-format', '--print'].every((flag) => help.stdout.includes(flag));
92
101
  features = { resume: helpOk && help.stdout.includes('--resume'), outputSchema: false };
@@ -99,12 +108,12 @@ function doctor(name) {
99
108
  copilot: ['--prompt', '--silent'],
100
109
  };
101
110
  if (available && compatible === null && HELP_FLAGS[value.provider]) {
102
- const help = spawnSync(value.command, ['--help'], { encoding: 'utf8', timeout: 10_000, shell: false });
111
+ const help = probeSync(value.command, [...prefix, '--help']);
103
112
  compatible = !help.error && help.status === 0 && HELP_FLAGS[value.provider].every((flag) => help.stdout.includes(flag));
104
113
  features = { resume: false, outputSchema: false };
105
114
  }
106
115
  else if (available && compatible === null && value.provider === 'opencode') {
107
- const help = spawnSync(value.command, ['run', '--help'], { encoding: 'utf8', timeout: 10_000, shell: false });
116
+ const help = probeSync(value.command, [...prefix, 'run', '--help']);
108
117
  compatible = !help.error && help.status === 0 && help.stdout.includes('--agent');
109
118
  features = { resume: false, outputSchema: false };
110
119
  }
@@ -32,12 +32,24 @@ import { SqliteGraphStore, SqliteMigrationRunner } from '../packages/adapter-sql
32
32
  import { buildRiskInput, changedFiles } from '../lib/core/risk-collect.js';
33
33
  import { emitOk, emitError, emitRejected } from '../lib/cli-output.js';
34
34
  const CONSTITUTION_PATH = '.context/architecture/constitution.json';
35
+ function rmWithRetry(target, attempts = 3) {
36
+ for (let i = 0; i < attempts; i++) {
37
+ try {
38
+ fs.rmSync(target, { recursive: true, force: true });
39
+ return;
40
+ }
41
+ catch {
42
+ if (i === attempts - 1)
43
+ throw new Error(`rmWithRetry: falhou após ${attempts} tentativas: ${target}`);
44
+ }
45
+ }
46
+ }
35
47
  function repoRoot() {
36
48
  return process.env.FORJA_GRAPH_ROOT ?? process.cwd();
37
49
  }
38
50
  /** Roda `buildRiskInput`/`checkConstitution` contra `worktreeRoot`, isolado do workspace real (D3). */
39
51
  async function assessWorktree(worktreeRoot, paths) {
40
- const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-db-'));
52
+ const tempBase = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-db-')));
41
53
  const database = new Database(path.join(tempBase, 'simulate.db'));
42
54
  new SqliteMigrationRunner(database).apply();
43
55
  const previousGraphRoot = process.env.FORJA_GRAPH_ROOT;
@@ -69,7 +81,7 @@ async function assessWorktree(worktreeRoot, paths) {
69
81
  finally {
70
82
  process.env.FORJA_GRAPH_ROOT = previousGraphRoot;
71
83
  database.close();
72
- fs.rmSync(tempBase, { recursive: true, force: true });
84
+ rmWithRetry(tempBase);
73
85
  }
74
86
  }
75
87
  function recommendationFor(testPassed, architectureCheck, risk) {
@@ -99,7 +111,7 @@ async function cmdSimulate(args) {
99
111
  const runner = new SpawnCommandRunner();
100
112
  const patchApplier = { apply: () => { throw new Error('simulate nunca promove — patchApplier.apply não deveria ser chamado'); }, revert: () => { } };
101
113
  const sandbox = new SandboxEngine(new InMemorySandboxStore(), new GitWorktreeBackend(runner, { repositoryRoot: repoRoot(), sourceRef: ref, patchApplier }));
102
- const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-'));
114
+ const tempBase = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-')));
103
115
  const worktreeRoot = path.join(tempBase, 'worktree');
104
116
  const runId = randomUUID();
105
117
  const session = await sandbox.create({ runId, root: worktreeRoot });
@@ -120,7 +132,7 @@ async function cmdSimulate(args) {
120
132
  // órfão na árvore real — algo que vale saber, mesmo sem abortar a simulação por causa disso.
121
133
  await sandbox.reject(session.id).catch((error) => { console.error(`simulate: aviso — reject do sandbox falhou: ${error instanceof Error ? error.message : String(error)}`); });
122
134
  await sandbox.destroy(session.id).catch((error) => { console.error(`simulate: aviso — destroy do sandbox falhou: ${error instanceof Error ? error.message : String(error)}`); });
123
- fs.rmSync(tempBase, { recursive: true, force: true });
135
+ rmWithRetry(tempBase);
124
136
  }
125
137
  // Fora do try/finally: o cleanup do sandbox já rodou, então as saídas que terminam o processo
126
138
  // (emit*) são seguras. `discard` = o gate do simulate dizendo "não promova" → rejected/exit 2
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "5.3.0",
3
+ "version": "5.3.1",
4
4
  "description": "ForjaJS é uma plataforma local-first para memória, contexto, governança e execução supervisionada de agentes de desenvolvimento",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -1,7 +1,7 @@
1
1
  # Spec: v6-agent-runtime-portable
2
2
 
3
3
  - **ID**: SPEC-059
4
- - **Status**: draft
4
+ - **Status**: done
5
5
  - **Owner**: allanpablo
6
6
  - **Criado em**: 2026-11-08
7
7
  - **Sprint alvo**: v6.0 Wave 2
@@ -31,12 +31,12 @@ Sem dependência nova, de propósito: o que falta são ~40 linhas de quoting que
31
31
  - **Como** contribuidor, **quero** escrever checks `type: 'command'` com comandos portáveis e vê-los rodar em qualquer SO, **para que** a suíte de evals não seja um ativo só de unix.
32
32
 
33
33
  ## 4. Critérios de aceite (Definition of Done)
34
- - [ ] AC-1: os quatro call sites de fronteira de agente passam por `lib/exec.ts` (`resolveCommand`, `spawnAgent`, `runShell`, `killTree`): `packages/llm/src/index.ts:123`, `scripts/llm-fit.ts:76,84,86,91,104,108`, `lib/agent-evals.ts:177,183` e `lib/agent-evals.ts:254`. Spawn de `git`, `node` e `process.execPath` continua como está — não é a fronteira em questão e mexer nele seria escopo emprestado.
35
- - [ ] AC-2 (segurança): o quoting de argumentos para `cmd.exe` é provado por teste com argumentos hostis — `"`, `&`, `|`, `>`, `<`, `%VAR%`, `^`, espaço, caminho com `\` — chegando ao processo-filho byte a byte como foi passado, e nenhum deles executando um segundo comando. O prompt do usuário e o comando do perfil são argumentos: sem este AC, o AC-1 trocava `EINVAL` por injeção. `shell: true` do Node nunca é usado (ele não escapa argumentos).
36
- - [ ] AC-3 (fixture não desvia do produto): o stub de agente dos testes é um `.cmd` no Windows e continua script com shebang em unix, executado pelo mesmo resolver do produto. Os 6 casos do inventário ficam verdes na célula Windows **sem skip**.
37
- - [ ] AC-4 (a árvore morre junto): em timeout, `runLlm` derruba filho e netos nos três SOs — no Windows por `taskkill /pid <pid> /T /F` ou equivalente, em POSIX pelo pid negativo como hoje. Teste: agente falso de dois níveis cujo neto escreve a cada 100ms para de escrever depois do grace, nos dois SOs. `exitCode: 124` / `errorCode: 'TIMEOUT'` não mudam.
38
- - [ ] AC-5 (diagnóstico honesto): binário não encontrável → `available: false` com `detail` dizendo o que foi procurado (caminho resolvido, `PATHEXT`); binário encontrável que falha ao executar → outro detail. O contrato `--json` (ADR-0082) e os campos existentes não mudam, só o conteúdo de `detail`.
39
- - [ ] AC-6 (checks `command`): `type: 'command'` roda por `runShell`, que usa `sh -c` em POSIX e `%ComSpec% /d /s /c` no Windows; as suítes de `templates/evals/agents/*.json` rodam inteiras nos três SOs. `CheckResult` não ganha estado novo nesta spec.
34
+ - [x] AC-1: os quatro call sites de fronteira de agente passam por `lib/exec.ts` (`resolveCommand`, `spawnAgent`, `runShell`, `killTree`): `packages/llm/src/index.ts:123`, `scripts/llm-fit.ts:76,84,86,91,104,108`, `lib/agent-evals.ts:177,183` e `lib/agent-evals.ts:254`. Spawn de `git`, `node` e `process.execPath` continua como está — não é a fronteira em questão e mexer nele seria escopo emprestado.
35
+ - [x] AC-2 (segurança): o quoting de argumentos para `cmd.exe` é provado por teste com argumentos hostis — `"`, `&`, `|`, `>`, `<`, `%VAR%`, `^`, espaço, caminho com `\` — chegando ao processo-filho byte a byte como foi passado, e nenhum deles executando um segundo comando. O prompt do usuário e o comando do perfil são argumentos: sem este AC, o AC-1 trocava `EINVAL` por injeção. `shell: true` do Node nunca é usado (ele não escapa argumentos).
36
+ - [x] AC-3 (fixture não desvia do produto): o stub de agente dos testes é um `.cmd` no Windows e continua script com shebang em unix, executado pelo mesmo resolver do produto. Os 6 casos do inventário ficam verdes na célula Windows **sem skip**.
37
+ - [x] AC-4 (a árvore morre junto): em timeout, `runLlm` derruba filho e netos nos três SOs — no Windows por `taskkill /pid <pid> /T /F` ou equivalente, em POSIX pelo pid negativo como hoje. Teste: agente falso de dois níveis cujo neto escreve a cada 100ms para de escrever depois do grace, nos dois SOs. `exitCode: 124` / `errorCode: 'TIMEOUT'` não mudam.
38
+ - [x] AC-5 (diagnóstico honesto): binário não encontrável → `available: false` com `detail` dizendo o que foi procurado (caminho resolvido, `PATHEXT`); binário encontrável que falha ao executar → outro detail. O contrato `--json` (ADR-0082) e os campos existentes não mudam, só o conteúdo de `detail`.
39
+ - [x] AC-6 (checks `command`): `type: 'command'` roda por `runShell`, que usa `sh -c` em POSIX e `%ComSpec% /d /s /c` no Windows; as suítes de `templates/evals/agents/*.json` rodam inteiras nos três SOs. `CheckResult` não ganha estado novo nesta spec.
40
40
 
41
41
  ## 5. Escopo
42
42
  **Dentro**:
@@ -80,4 +80,4 @@ Levantamento de 2026-11-08, branch `feat/v6-wave1` (PR #83), por leitura de cód
80
80
  - **Restrição do Node**: spawn de `.bat`/`.cmd` sem `shell: true` lança `EINVAL` desde 18.20.2 / 20.12.2 / 21.7.3 (endurecimento da CVE-2024-27980). A matriz do CI roda Node 22 e 24: as duas células estão do lado endurecido, então não há versão suportada em que o código atual funcione no Windows.
81
81
  - **Comando do check template é portável, o launcher não**: `"run": "node --test"` em `templates/evals/agents/teste-do-criterio.json:21` roda igual em `cmd.exe`; o que impede é o `sh` fixo na linha 254.
82
82
  - **Convenção que já existe no repo**: `lib/project-wiring.ts:98` usa `where` no Windows e `which` no resto. Também por isso o caminho é um módulo só — não quatro remendos de plataforma espalhados pelos call sites.
83
- - **Estado**: spec em draft, nenhuma linha de produto escrita. A implementação depende de aprovação e roda na mesma branch da Wave 2.
83
+ - **Estado**: implementado em 2026-11-16 (PR #86, branch `fix/windows-inventory`). `lib/exec.ts` + `test/exec.test.js` (14 testes). CI Windows verde (run 43804567909). SPEC-056 AC-4 fechado.
@@ -28,7 +28,7 @@ CI que roda a suíte em matriz multi-OS e cobra, a cada push, dois ratchets vers
28
28
  - [x] AC-1: Job `test` roda em matriz multi-OS (`ubuntu-latest` × Node 22/24, `macos-latest` e `windows-latest` × Node 24) com `fail-fast: false`; falha em qualquer célula bloqueia.
29
29
  - [x] AC-2: Check `type-debt` no catálogo do doctor conta `any` explícito (`: any`, `as any`, `<any>`, `any[]`) em `bin/lib/scripts/apps` (`.ts`/`.tsx`, fora `.d.ts`, com template literals descartados) e compara com `anyCeiling` versionado em `lib/core/quality-budget.json`: acima do teto → `critical` fail; abaixo → `warn` mandando descer o teto. Sem ESLint.
30
30
  - [x] AC-3: `forja quality:coverage` roda **a mesma suíte** com `--experimental-test-coverage`, lê a linha `all files` da tabela e cobra `coverageLineFloor` (exit 2 abaixo do piso, exit 1 se a suíte falhar, `--json` no contrato do ADR-0082). O CI usa esse passo na célula ubuntu **no lugar** de `npm test` — custo adicional zero.
31
- - [ ] AC-4: Testes que dependem de comportamento unix (permissões, `bin:` shells) têm skip condicional explícito e justificado, não falha silenciosa — a levantar pela primeira rodada verde/vermelha das células macOS/Windows. **Levantado (2026-11-06)**: macOS 665/665; Windows 23 → 14 → 11 → 10 em quatro rodadas, com 7 causas de produto/robustez fechadas no caminho e o *skip justificado* escrito para o caso SIGTERM. Restam 3 causas no inventário — uma delas (runtime de agentes) é lacuna de produto, não teste. Ver Evidências.
31
+ - [x] AC-4: Testes que dependem de comportamento unix (permissões, `bin:` shells) têm skip condicional explícito e justificado, não falha silenciosa — a levantar pela primeira rodada verde/vermelha das células macOS/Windows. **Fechado (2026-11-16, PR #86)**: Windows 665/665 verdes (1 skip justificado: SIGTERM). `continue-on-error` removido do ci.yml — toda célula bloqueia o merge. Ver Evidências.
32
32
  - [x] AC-5: Tempo total do CI não cresce por causa das réguas: a cobertura substitui o passo de teste no ubuntu (não soma), e as células novas rodam em paralelo.
33
33
  - [x] AC-6: O stdout do contrato `--json` nunca sai truncado — `lib/cli-output.ts` escreve com `fs.writeSync` em laço antes do `process.exit()`, com teste de regressão de payload de 400KB (6× o buffer do pipe).
34
34
 
@@ -83,7 +83,7 @@ Medições de 2026-11-05, branch `feat/v6-wave1`:
83
83
  5. *CRLF na régua de derivação de doc* — `commands-ref` comparava `docs/commands.md` byte a byte com o renderizado; em checkout CRLF isso é "diverge" falso, e o `tools:doctor` do repo ficava vermelho sem nada estar velho. A comparação normaliza `\r\n`. **Regra geral que ficou**: o framework valida texto de *projeto do usuário*, que chega em CRLF seja lá o que a gente fizer no nosso repo — tolerar é o certo, `.gitattributes` não resolve o mundo.
84
84
  6. *Handle vazado no próprio teste* — o `antes` do teste de sync incremental abria uma conexão `readonly` e nunca fechava. Em unix é inocente; em Windows tranca o `.db` até o processo do runner acabar, e o `rmSync` do temp volta EPERM **para sempre** (a retry de 10×100ms da rodada 1 só provou que não era transitório). Fecha na leitura.
85
85
  7. *Sinal POSIX* — `test/server-shutdown.test.js` manda SIGTERM num filho: o sinal não existe em Windows e o probe usa `--import tsx`, opção de runtime que a célula não resolve. Este é o **skip explícito e justificado** que o AC-4 pedia, não um conserto; o contrato continua provado nas células unix. Está marcado como skipped na rodada 3, não como aprovado.
86
- - **Inventário aberto (a célula está `continue-on-error` só por isto)** — 3 causas, 10 casos na rodada 4:
86
+ - **Inventário fechado (2026-11-16, PR #86, branch `fix/windows-inventory`)** — 3 causas, 10 casos → 0:
87
87
  - *Runtime de agentes é unix por construção* (6 casos na rodada 4: `test/llm-resume-validation.test.js:142` com `spawn EFTYPE`; `test/agent-evals.test.js:85` e os AC-4/AC-5/AC-6 com `agent.args` nunca escrito; `test/llm-claude-adapter.test.js:99`; `test/llm-integration.test.js:111` — e os 2 casos do AC-1, que eram desta mesma família e ficaram verdes na rodada 2, o que confirma que a causa deles era o CRLF das skills e não o stub). Os testes modelam o CLI do agente como script com shebang, e é assim que ele falha — mas a causa é do produto, em três lugares lidos no código, não chutados do log:
88
88
  - `scripts/llm-fit.ts:76,84,91,104,108` sondam o binário com **`shell: false`** explícito. Em Windows o shim que `npm i -g` instala é `codex.cmd`/`claude.cmd`, e Node recusa spawnar `.cmd` sem `shell: true` (endurecimento da CVE-2024-27980). O `llm:probe` não tem como reportar features de um agente instalado nesse SO.
89
89
  - `lib/agent-evals.ts:254` executa o check `type: 'command'` com **`spawnSync('sh', ['-c', …])`** — sem `sh`, o check inteiro é inaplicável.
@@ -91,9 +91,14 @@ Medições de 2026-11-05, branch `feat/v6-wave1`:
91
91
  Não é para pular: é portabilidade do `llm:run`/`llm:probe`/`eval:agents`, e merece spec própria — redigida em 2026-11-08 como **SPEC-059 (`specs/v6-agent-runtime-portable`, Wave 2)**: caminho resolvido por `where`/`PATHEXT`, `sh -c` trocado por launcher de shell portável, e o kill do timeout derrubando a árvore.
92
92
  - *`git worktree`*: os 3 de `test/simulate-cli.test.js` (o `worktree list` antes/depois não fecha igual).
93
93
  - *`spec:trace` sem critérios no projeto gerado*: único resto da `jornada` nas quatro rodadas, que já ficou verde em `project:new`, `project:wire`, `context:smart` e `tools:doctor` — as causas 1/2/5 eram a jornada. O que a rodada 4 permite **eliminar**: não é a família do separador de caminho (`loadSpecs` lê o slug por `readdirSync`, e `listFiles` usa `git ls-files`, que fala POSIX por protocolo), não é CRLF na leitura do checklist (`AC_LINE` termina em `(.+)$`, que engole o `\r`), e não é a contagem de *tokens por critério* (AC-7 da SPEC-053) — `0/0` vem de `trace.totals`, antes de qualquer preço. O que fica de hipótese, sem prova: `specs/` vazio ou `readdirSync` lançando no `root` resolvido pela CLI em Windows (a função devolve `[]` nesse caso, e `0/0` é exatamente o que isso produz). Precisa de uma célula com diagnostico impresso, não de mais um patch adivinhado.
94
- - **Regra de saída**: tirar `continue-on-error` da matriz é o gate de que o inventário zerou. A linha existe no `ci.yml` com esta frase ao lado, para não virar mobília.
94
+ - **Regra de saída cumprida (2026-11-16)**: `continue-on-error` removido do `ci.yml`. Toda célula bloqueia o merge. O gate de que o inventário zerou está fechado.
95
95
  - **Rastreabilidade fechada (2026-11-09)**: `spec:trace v6-quality-gates` marcava **1/6** critérios com teste, embora AC-1/2/3/5/6 estivessem implementados e dois deles já tivessem teste real. Duas causas diferentes, tratadas de forma diferente:
96
96
  - *Faltava a citação, não o teste* (AC-2, AC-6): os 6 testes do ratchet `type-debt` em `test/health.test.js` e o payload de 400KB em `test/cli-output.test.js` já provavam o critério — só não escreviam `SPEC-056 AC-n`, que é o que o trace lê. Marcados. Nenhum teste novo: inventar um segundo teste para o mesmo comportamento inflaria a métrica sem aumentar a garantia.
97
97
  - *Faltava teste mesmo* (AC-3): a régua vivia inteira dentro de `scripts/coverage-gate.ts`, cujo caminho de execução é spawnar a suíte — testá-lo de ponta a ponta seria rodar a suíte dentro da suíte. A leitura da linha `all files`, a leitura do piso e a tabela de decisão saíram para `lib/core/coverage-gate.ts`, e o script virou coleta + emissão. `test/coverage-gate.test.js` (10) prova o que o script não podia provar: **suíte verde com tabela ausente é exit 1, nunca OK** (o formato do Node já mudou uma vez), processo morto por sinal não sai 0, e no piso exato passa — é ratchet, não folga.
98
98
  - *Propriedade de arquivo que nenhuma suíte executa* (AC-1, AC-5): `test/ci-workflow.test.js` (7) lê o `ci.yml` como texto — sem parser YAML, pela mesma razão do §2: não importar uma segunda máquina para medir o que já se mede. Prova as 4 células efetivas (ubuntu×22/24, macos×24, windows×24), o `fail-fast: false`, e que `continue-on-error` aparece **uma vez**, condicionado a `windows-latest`, com a regra de saída ao lado. Do lado do AC-5, prova que os dois passos de teste têm `if:` complementares e que cada um aparece uma única vez — nenhuma célula roda a suíte duas vezes.
99
99
  - **Medido depois**: `spec:trace v6-quality-gates` → **6/6**. AC-4 já era rastreado (o skip justificado do SIGTERM e o CRLF das skills) e continua com o checkbox aberto porque o inventário acima não zerou — teste não fecha inventário de produto. `npm test` → **683/683**, 0 skipped (666 + 17 novos). `forja quality:coverage` → `OK cobertura de linhas 91.84% (piso 90%) · branches 79.91% · funções 88.03%`, exit 0 — 0,04pp acima do estado anterior, com a régua agora coberta pelos próprios testes. `forja tools:doctor` → `OK type-debt 357 any explícitos, no teto (357)`: nenhum `any` novo. `npm run types:check` → 0 erros.
100
+ - **AC-4 fechado (2026-11-16, PR #86)**: as 3 causas restantes do inventário zeraram em 6 commits na branch `fix/windows-inventory`:
101
+ - *Runtime de agentes* (6 casos): `lib/exec.ts` novo (SPEC-059) — `resolveCommand` com `where`/PATHEXT preferindo `.cmd/.exe`, `spawnAgent` com quoting cmd.exe `/d /s /c` + aspas externas, `killTree` com `taskkill /T /F`, `runShell` portável. Fixtures Windows usam `command: process.execPath, commandArgs: [script.mjs]` (node direto, sem stdin via cmd.exe). Doctor prepende `commandArgs`. `buildLlmExecution` põe `commandArgs` antes do subcomando `exec`.
102
+ - *git worktree* (3 casos): `resolveCommand` prefere extensão executável (npm.cmd sobre script sh sem extensão); `sandboxEnvironment` ganha APPDATA/LOCALAPPDATA/COMSPEC/PATHEXT; `realpathSync` nos mkdtemp; cleanup com retry.
103
+ - *spec:trace 0/0* (1 caso): CRLF no `parseCriteria` (`split(/\r?\n/)`).
104
+ - **CI run 43804567909**: `test (windows-latest, 24.x)` → **success**. `continue-on-error` removido. `npm test` local → **1006/1006**, 1 skipped (SIGTERM). `npm run types:check` → 0 erros.