@ps-neko/nekowork 0.1.0-alpha.0

package/scripts/agents/dispatch.js

@@ -0,0 +1,144 @@
+// 에이전트 dispatch. agent.md frontmatter 읽고 provider runner 로 위임.
+// 입력 / 출력은 표준화된 JSON 스키마. 단계 간 컨텍스트는 핸드오프 파일로만.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+
+import { runMock } from './runners/mock.js';
+import { runClaude } from './runners/claude.js';
+import { runCodex } from './runners/codex.js';
+import { runGemini } from './runners/gemini.js';
+import { decide as routeDecide, trace as routeTrace } from '../lib/router.js';
+import { record as costRecord } from '../lib/costs.js';
+import { classifyRisk } from '../lib/risk-classifier.js';
+
+const RUNNERS = {
+  mock: runMock,
+  claude: runClaude,
+  codex: runCodex,
+  gemini: runGemini,
+};
+
+/**
+ * 에이전트 한 번 호출.
+ * @param {object} opts
+ * @param {string} opts.agent           - agent name (예: 'planner')
+ * @param {string} opts.stage           - 단계 이름 (예: 'plan')
+ * @param {string} opts.task            - 사용자 작업 한 줄
+ * @param {object} opts.context         - 디스크 핸드오프 + PRD 등 자료
+ * @param {boolean} [opts.live=false]   - 실 LLM 호출
+ * @param {string}  [opts.providerOverride] - provider 강제 지정
+ * @param {string}  [opts.harnessRoot]
+ * @param {string}  [opts.projectRoot]
+ * @returns {Promise<object>} 핸드오프 객체 (handoff.schema.json 준수)
+ */
+export async function dispatch(opts) {
+  const harnessRoot = opts.harnessRoot || process.cwd();
+  const projectRoot = opts.projectRoot || harnessRoot;
+  const agentFile = path.join(harnessRoot, 'agents', `${opts.agent}.md`);
+  if (!fs.existsSync(agentFile)) throw new Error(`agent file not found: ${opts.agent}`);
+
+  const raw = fs.readFileSync(agentFile, 'utf8');
+  const fmMatch = raw.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!fmMatch) throw new Error(`agent ${opts.agent} 의 frontmatter 없음`);
+  const fm = YAML.parse(fmMatch[1]);
+  const body = raw.slice(fmMatch[0].length).trim();
+
+  const provider = opts.providerOverride || (opts.live ? fm.provider : 'mock');
+  const runner = RUNNERS[provider];
+  if (!runner) throw new Error(`알 수 없는 provider: ${provider}`);
+
+  // routing trace
+  if (opts.sessionDir) {
+    try {
+      const decision = routeDecide({
+        stage: opts.stage,
+        task: opts.task,
+        files: opts.context?.files || [],
+        ecoMode: !!process.env.HARNESS_ECO,
+        riskLevel: classifyRisk({ task: opts.task || '', files: opts.context?.files || [] }).risk,
+        harnessRoot,
+      });
+      decision.provider = provider;
+      decision.model = fm.model;
+      routeTrace(opts.sessionDir, decision, { stage: opts.stage, task: opts.task });
+    } catch { /* trace 실패는 dispatch 자체를 막지 않음 */ }
+  }
+
+  const startTs = Date.now();
+  const result = await runner({
+    agent: fm.name,
+    stage: opts.stage,
+    task: opts.task,
+    model: fm.model,
+    sandbox: opts.sandboxOverride || fm.sandbox,
+    networkAccess: fm.network_access,
+    disallowedTools: fm.disallowedTools || [],
+    promptBody: body,
+    context: opts.context || {},
+    harnessRoot,
+    projectRoot,
+    executionMode: opts.executionMode,
+  });
+  const durMs = Date.now() - startTs;
+
+  // cost record (mock 도 0 으로 기록 — 호출 카운트 가시성)
+  try {
+    costRecord({
+      session: opts.sessionId || 'default',
+      stage: opts.stage,
+      agent: fm.name,
+      provider,
+      model: fm.model,
+      input_tokens: result.usage?.input_tokens || 0,
+      output_tokens: result.usage?.output_tokens || 0,
+      duration_ms: durMs,
+    });
+  } catch { /* 비용 기록 실패는 무시 */ }
+
+  // 표준화 + 메타데이터 부착. 런너의 임의 필드는 통과시키지 않고,
+  // orchestrator 가 명시적으로 쓰는 메타데이터만 보존한다.
+  const standardKeys = new Set([
+    'decided','rejected','risks','files','remaining','issues','verdict','confidence','usage',
+  ]);
+  const passthroughKeys = new Set(['prdSeed', 'diffPath', 'executionWorkspace']);
+  const passthrough = {};
+  for (const [k, v] of Object.entries(result || {})) {
+    if (!standardKeys.has(k) && passthroughKeys.has(k)) passthrough[k] = v;
+  }
+
+  const handoff = {
+    stage: opts.stage,
+    agent: fm.name,
+    round: opts.context?.round || 1,
+    session_id: opts.sessionId || undefined,
+    timestamp: new Date().toISOString(),
+    duration_ms: durMs,
+    provider,
+    model: fm.model,
+    decided: result.decided ?? '',
+    rejected: result.rejected ?? '',
+    risks: result.risks ?? '',
+    files: result.files ?? [],
+    remaining: result.remaining ?? '',
+    issues: result.issues ?? [],
+    verdict: result.verdict,
+    ...passthrough,
+  };
+  if (result.confidence != null) handoff.confidence = result.confidence;
+  for (const [k, v] of Object.entries(handoff)) {
+    if (v === undefined) delete handoff[k];
+  }
+  return handoff;
+}
+
+/** agent.md frontmatter 파싱. 파일이 없거나 frontmatter 없으면 null 반환. */
+export function loadAgentFrontmatter(agentName, root = process.cwd()) {
+  const f = path.join(root, 'agents', `${agentName}.md`);
+  if (!fs.existsSync(f)) return null;
+  const raw = fs.readFileSync(f, 'utf8');
+  const m = raw.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  return YAML.parse(m[1]);
+}

package/scripts/agents/runners/claude.js

@@ -0,0 +1,214 @@
+// Claude runner.
+// Default live mode uses the local Claude Code CLI subscription/OAuth session.
+// Set HARNESS_CLAUDE_RUNNER=sdk to opt into Anthropic SDK/API-key mode.
+
+import { assertDelegatedCliAuth } from '../../core/auth-guard.js';
+import { resolveProviderCli } from '../../core/cli-resolver.js';
+import { withGitMutationGuard } from '../../core/git-mutation-guard.js';
+import { extractJson } from '../../core/json-extractor.js';
+import { spawnAndCollect } from '../../core/subprocess.js';
+
+const MODEL_MAP = {
+  opus: 'claude-opus-4-7',
+  sonnet: 'claude-sonnet-4-6',
+  haiku: 'claude-haiku-4-5-20251001',
+};
+
+export async function runClaude(args) {
+  const runner = (process.env.HARNESS_CLAUDE_RUNNER || 'cli').toLowerCase();
+  if (runner === 'sdk') return runClaudeSdk(args);
+  return runClaudeCli(args);
+}
+
+async function runClaudeSdk(args) {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    throw new Error('ANTHROPIC_API_KEY is required when HARNESS_CLAUDE_RUNNER=sdk. Use Claude Code CLI login for the default runner.');
+  }
+
+  let Anthropic;
+  try {
+    ({ default: Anthropic } = await import('@anthropic-ai/sdk'));
+  } catch {
+    throw new Error('@anthropic-ai/sdk is not installed. Install it or use the default Claude Code CLI runner.');
+  }
+
+  const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+  const modelId = MODEL_MAP[args.model] || args.model;
+  const systemPrompt = buildSystem(args);
+  const userPrompt = buildUserMessage(args);
+
+  const resp = await client.messages.create({
+    model: modelId,
+    max_tokens: 4096,
+    system: systemPrompt,
+    messages: [{ role: 'user', content: userPrompt }],
+  });
+
+  const text = resp.content.map(b => (b.type === 'text' ? b.text : '')).join('').trim();
+  const jsonText = extractJson(text);
+  if (!jsonText) {
+    throw new Error('Claude SDK response did not contain JSON. raw:\n' + text.slice(0, 500));
+  }
+
+  let parsed;
+  try { parsed = JSON.parse(jsonText); }
+  catch (e) { throw new Error('Claude SDK response JSON parse failed: ' + e.message); }
+
+  return parsed;
+}
+
+async function runClaudeCli(args) {
+  assertDelegatedCliAuth('claude');
+
+  const cwd = args.projectRoot || args.harnessRoot || process.cwd();
+  const trustRoots = [cwd, args.harnessRoot].filter(Boolean);
+  const claudeBin = resolveProviderCli('claude', { root: cwd, roots: trustRoots });
+  if (!claudeBin) {
+    throw new Error('claude CLI is not installed. Install/login to Claude Code, or explicitly use HARNESS_CLAUDE_RUNNER=sdk with ANTHROPIC_API_KEY.');
+  }
+
+  const systemPrompt = buildSystem(args);
+  const userPrompt = buildUserMessage(args);
+  const modelId = process.env.HARNESS_CLAUDE_MODEL || args.model || 'sonnet';
+  const cliArgs = buildCliArgs(args, modelId, systemPrompt);
+
+  const run = () => spawnAndCollect(claudeBin, cliArgs, userPrompt, {
+    label: 'claude',
+    // 풀사이클 stage 3 implement 는 verify smoke(~25s) 보다 응답이 길어
+    // 180s default 로는 timeout 다발. 600s (10분) 로 상향. 환경변수로 추가 조정 가능.
+    timeoutMs: Number(process.env.HARNESS_CLAUDE_TIMEOUT_S || 600) * 1000,
+    cwd,
+  });
+  const stdout = args.executionMode === 'workspace-write'
+    ? await run()
+    : await withGitMutationGuard(
+      cwd,
+      run,
+      { label: 'claude', allowEnvKey: 'HARNESS_CLAUDE_ALLOW_WORKSPACE_MUTATION' },
+    );
+  const wrapper = parseCliJson(stdout);
+  const text = typeof wrapper?.result === 'string' ? wrapper.result : stdout;
+  const jsonText = extractJson(text);
+  if (!jsonText) {
+    throw new Error('Claude CLI response did not contain JSON. raw:\n' + text.slice(0, 500));
+  }
+
+  let parsed;
+  try { parsed = JSON.parse(jsonText); }
+  catch (e) { throw new Error('Claude CLI response JSON parse failed: ' + e.message); }
+
+  if (wrapper?.usage) parsed.usage = normalizeCliUsage(wrapper.usage);
+  return parsed;
+}
+
+function buildCliArgs(a, modelId, systemPrompt) {
+  const args = [
+    '-p',
+    '--output-format', 'json',
+    '--no-session-persistence',
+    '--model', modelId,
+    '--system-prompt', systemPrompt,
+  ];
+
+  if (a.executionMode === 'workspace-write') {
+    args.push(
+      '--permission-mode', process.env.HARNESS_CLAUDE_EXEC_PERMISSION_MODE || 'acceptEdits',
+      '--allowedTools', process.env.HARNESS_CLAUDE_EXEC_TOOLS || 'Edit Write MultiEdit',
+    );
+  } else {
+    args.push('--tools', '', '--permission-mode', 'plan');
+  }
+
+  return args;
+}
+
+function buildSystem(a) {
+  const tools = a.disallowedTools?.length
+    ? `\nDisallowed tools: ${a.disallowedTools.join(', ')}`
+    : '';
+  return `You are the HARNESS agent "${a.agent}" running stage "${a.stage}".${tools}
+Sandbox: ${a.sandbox || 'workspace-write'}.
+Output rules: respond with ONE JSON object conforming to schemas/handoff.schema.json.
+No prose outside JSON. Korean for natural-language fields.
+${a.executionMode === 'workspace-write'
+    ? 'Workspace-write execution mode: edit files in this isolated git worktree if needed, but do not commit or push. Finish by returning the JSON handoff with changed files and evidence.'
+    : 'Non-interactive handoff mode: do not call tools, edit files, run shell commands, wait for approvals, or make commits. If the agent body asks you to implement, test, or commit, summarize the intended change and evidence in JSON only.'}
+Keep the JSON concise so the CLI can finish promptly.
+
+Agent body:
+${a.promptBody}`;
+}
+
+function buildUserMessage(a) {
+  const lines = [];
+  lines.push('## Task');
+  lines.push(a.task || '(none)');
+  lines.push('');
+  if (a.context?.prd) {
+    lines.push('## PRD');
+    lines.push('```json');
+    lines.push(JSON.stringify(a.context.prd, null, 2));
+    lines.push('```');
+  }
+  if (a.context?.acceptanceCriteria?.length) {
+    lines.push('## Acceptance Criteria');
+    for (const ac of a.context.acceptanceCriteria) {
+      lines.push(`- ${ac.id}: ${ac.desc}`);
+    }
+    lines.push('');
+  }
+  if (a.context?.qualityChecklist?.length) {
+    lines.push(`## Profile Quality Checklist${a.context.profile ? ` (${a.context.profile})` : ''}`);
+    for (const item of a.context.qualityChecklist) {
+      lines.push(`- ${item}`);
+    }
+    lines.push('');
+  }
+  if (a.context?.diff) {
+    lines.push('## Git Diff');
+    lines.push('```diff');
+    lines.push(String(a.context.diff).slice(0, 20000));
+    lines.push('```');
+  }
+  if (a.context?.priorHandoffs?.length) {
+    lines.push('## Prior handoffs');
+    for (const h of a.context.priorHandoffs) {
+      lines.push(`### ${h.stage}`);
+      lines.push(`Decided: ${h.decided}`);
+      lines.push(`Files: ${(h.files || []).join(', ')}`);
+      if (h.verdict) lines.push(`Verdict: ${h.verdict}`);
+      lines.push('');
+    }
+  }
+  if (a.context?.round && a.context.round > 1) {
+    lines.push(`## Round ${a.context.round}: consider unresolved issues from earlier rounds.`);
+  }
+  return lines.join('\n');
+}
+
+function parseCliJson(stdout) {
+  const text = String(stdout || '').trim();
+  if (!text) return null;
+  try { return JSON.parse(text); }
+  catch { return null; }
+}
+
+function normalizeCliUsage(usage) {
+  const last = Array.isArray(usage.iterations) ? usage.iterations.at(-1) : null;
+  return {
+    input_tokens: Number(last?.input_tokens ?? usage.input_tokens ?? 0),
+    output_tokens: Number(last?.output_tokens ?? usage.output_tokens ?? 0),
+    cache_creation_input_tokens: Number(last?.cache_creation_input_tokens ?? usage.cache_creation_input_tokens ?? 0),
+    cache_read_input_tokens: Number(last?.cache_read_input_tokens ?? usage.cache_read_input_tokens ?? 0),
+    total_cost_usd: Number(usage.total_cost_usd ?? 0),
+  };
+}
+
+export {
+  buildSystem as _buildSystem,
+  buildCliArgs as _buildCliArgs,
+  buildUserMessage as _buildUserMessage,
+  extractJson,
+  parseCliJson as _parseCliJson,
+  normalizeCliUsage as _normalizeCliUsage,
+};

package/scripts/agents/runners/codex.js

@@ -0,0 +1,233 @@
+// Codex runner: OpenAI Codex CLI 를 subprocess 로 호출.
+// 환경: codex 바이너리 필요. 없으면 throw.
+//
+// 호출 패턴 (codex 0.124.0+ 비대화형 검증):
+//   codex exec --sandbox read-only [--profile <name>] < prompt
+// stdin 으로 prompt 전달, stdout 의 `codex` 라벨 다음 JSON 객체를 응답으로 사용.
+//
+// Codex 는 Claude 컨텍스트를 받지 않는다. 입력은:
+//   - system prompt (codex-reviewer 페르소나)
+//   - git diff
+//   - handoffs/04-self-review.md (Claude self-review 5필드 요약)
+//   - prd-<id>.md
+//
+// 출력: stdout 의 JSON. 5필드 + issues + verdict.
+
+import { assertDelegatedCliAuth } from '../../core/auth-guard.js';
+import { resolveProviderCli } from '../../core/cli-resolver.js';
+import { withGitMutationGuard } from '../../core/git-mutation-guard.js';
+import { extractJson } from '../../core/json-extractor.js';
+import { spawnAndCollect } from '../../core/subprocess.js';
+import { classifyCategory, classifySeverity, deriveVerdict, severityCounts } from '../../lib/severity.js';
+
+export async function runCodex(args) {
+  assertDelegatedCliAuth('codex');
+
+  const cwd = args.projectRoot || args.harnessRoot || process.cwd();
+  const trustRoots = [cwd, args.harnessRoot].filter(Boolean);
+  const codexBin = resolveProviderCli('codex', { root: cwd, roots: trustRoots });
+  if (!codexBin) {
+    throw new Error('codex CLI 미설치. https://github.com/openai/codex 또는 --provider=mock 사용.');
+  }
+
+  const stage = args.stage === 'codex-challenge' ? 'challenge' : 'review';
+  const promptText = buildPrompt(args);
+
+  // codex 0.124.0+ 비대화형 모드: `codex exec` + 명시적 sandbox.
+  // 인증·CLI 마찰을 줄이기 위해 stdin 으로 직접 prompt 전달.
+  const cliArgs = ['exec', '--sandbox', 'read-only'];
+
+  // profile 은 사용자의 `~/.codex/config.toml` 의존이므로 환경변수로 옵션화.
+  // stage 별 분리: HARNESS_CODEX_PROFILE_REVIEW / HARNESS_CODEX_PROFILE_CHALLENGE.
+  // 또는 공통: HARNESS_CODEX_PROFILE.
+  const profile = process.env[`HARNESS_CODEX_PROFILE_${stage.toUpperCase()}`]
+    || process.env.HARNESS_CODEX_PROFILE;
+  if (profile) {
+    cliArgs.push('--profile', profile);
+  }
+  if (process.env.HARNESS_CODEX_EXTRA_ARGS) {
+    cliArgs.push(...process.env.HARNESS_CODEX_EXTRA_ARGS.split(' '));
+  }
+
+  const stdout = await withGitMutationGuard(
+    cwd,
+    () => spawnAndCollect(codexBin, cliArgs, promptText, {
+      label: 'codex',
+      timeoutMs: Number(process.env.HARNESS_CODEX_TIMEOUT_S || 180) * 1000,
+      cwd,
+    }),
+    { label: 'codex', allowEnvKey: 'HARNESS_CODEX_ALLOW_WORKSPACE_MUTATION' },
+  );
+  // codex CLI 0.125+ stdout: "user\n<prompt echo>\n\ncodex\n<응답>".
+  // echo 된 user prompt 에 ```json``` 펜스가 있으면 extractJson 이 오매칭하므로,
+  // "codex" 라벨 (단독 줄) 이후만 파싱한다.
+  const labelMatch = stdout.match(/(^|\n)codex\r?\n/);
+  const cleaned = labelMatch
+    ? stdout.slice(labelMatch.index + labelMatch[0].length)
+    : stdout;
+  const json = extractJson(cleaned);
+  if (!json) {
+    throw new Error('Codex 응답에서 JSON 을 찾지 못함. raw:\n' + stdout.slice(0, 500));
+  }
+  return normalizeHandoff(JSON.parse(json));
+}
+
+function buildPrompt(a) {
+  const lines = [];
+  if (a.stage === 'codex-review') {
+    lines.push('# 시스템 프롬프트');
+    lines.push('당신은 이 변경을 처음 보는 시니어 리뷰어다. Claude self-review 가 놓쳤을 critical / high 만 보고하라.');
+    lines.push('');
+  } else if (a.stage === 'codex-challenge') {
+    lines.push('# 시스템 프롬프트');
+    lines.push('당신은 적대적 보안 리서처다. 이 코드를 부수려 들어라. 구체적 공격 시나리오를 issue.why 에 기술하라.');
+    lines.push('');
+  }
+  lines.push('출력은 schemas/handoff.schema.json 에 부합하는 JSON 객체 하나.');
+  lines.push('');
+  lines.push('# 입력');
+  if (a.context?.diff) {
+    lines.push('## Git Diff');
+    lines.push('```diff');
+    lines.push(String(a.context.diff).slice(0, 30000));
+    lines.push('```');
+  }
+  if (a.context?.acceptanceCriteria?.length) {
+    lines.push('## Acceptance Criteria');
+    for (const ac of a.context.acceptanceCriteria) {
+      lines.push(`- ${ac.id}: ${ac.desc}`);
+    }
+  }
+  if (a.context?.qualityChecklist?.length) {
+    lines.push(`## Profile Quality Checklist${a.context.profile ? ` (${a.context.profile})` : ''}`);
+    for (const item of a.context.qualityChecklist) {
+      lines.push(`- ${item}`);
+    }
+  }
+  if (a.context?.evidencePolicy?.evidenceWarningRequired) {
+    lines.push('## Evidence Requirements');
+    lines.push('For critical, high, or gate-required findings, include claim, evidence, required_fix, confidence, and gate_required.');
+    if (a.context.evidencePolicy.strictQuality) {
+      lines.push('Strict quality mode is active: missing evidence or acceptance coverage can block ship readiness.');
+    }
+  }
+  if (a.context?.priorHandoffs?.length) {
+    lines.push('## 이전 단계 핸드오프 (5필드만)');
+    for (const h of a.context.priorHandoffs) {
+      lines.push(`### ${h.stage}`);
+      lines.push(`- Decided: ${h.decided}`);
+      lines.push(`- Files: ${(h.files || []).join(', ')}`);
+      if (h.verdict) lines.push(`- Verdict: ${h.verdict}`);
+    }
+  }
+  if (a.context?.prd) {
+    lines.push('## PRD');
+    lines.push('```json');
+    lines.push(JSON.stringify(a.context.prd, null, 2));
+    lines.push('```');
+  }
+  lines.push('');
+  lines.push('Review issue fields should be evidence-based when possible: claim, evidence, required_fix, confidence, gate_required.');
+  return lines.join('\n');
+}
+
+function normalizeHandoff(raw) {
+  if (!raw || typeof raw !== 'object') return raw;
+
+  const pick = (...keys) => {
+    for (const key of keys) {
+      if (raw[key] !== undefined) return raw[key];
+    }
+    return undefined;
+  };
+
+  const rawIssues = pick('issues', 'Issues');
+  const rawRisks = pick('risks', 'Risks');
+  const issueSource = Array.isArray(rawIssues) ? rawIssues : (Array.isArray(rawRisks) ? rawRisks : []);
+  const issues = issueSource.map(normalizeIssue);
+
+  // verdict 결정 전에 confidence / blastRadius 추출 — deriveVerdict opts 로 전달.
+  const confRaw = pick('confidence', 'Confidence');
+  const confNum = confRaw != null ? Number(confRaw) : NaN;
+  const confidence = Number.isFinite(confNum) ? confNum : undefined;
+  const filesArr = normalizeFiles(pick('files', 'Files'));
+  const blastRadius = filesArr.length;
+
+  const lower = {
+    decided: stringifyField(pick('decided', 'Decided', 'decision', 'Decision')),
+    rejected: stringifyField(pick('rejected', 'Rejected')),
+    risks: stringifyField(Array.isArray(rawRisks) ? rawRisks.map(r => r.issue || r.summary || r.message || JSON.stringify(r)).join('; ') : rawRisks),
+    files: filesArr,
+    remaining: stringifyField(pick('remaining', 'Remaining')),
+    issues,
+    verdict: normalizeVerdict(pick('verdict', 'Verdict'), issues, pick('decided', 'Decided'), { confidence, blastRadius }),
+  };
+
+  if (confidence !== undefined) lower.confidence = confidence;
+
+  return lower;
+}
+
+function normalizeIssue(issue) {
+  const i = issue && typeof issue === 'object' ? issue : { summary: String(issue || '') };
+  const summary = String(i.summary || i.claim || i.issue || i.message || i.title || '').slice(0, 200) || 'Codex reported an issue';
+  const confidence = Number(i.confidence);
+  const normalized = {
+    severity: i.severity,
+    category: i.category,
+    file: i.file || i.path,
+    line: Number.isInteger(i.line) ? i.line : undefined,
+    claim: i.claim,
+    evidence: i.evidence,
+    summary,
+    why: i.why || i.issue || i.message,
+    required_fix: i.required_fix ?? undefined,
+    suggested_fix: i.suggested_fix ?? i.fix ?? null,
+    confidence: Number.isFinite(confidence) ? confidence : undefined,
+    gate_required: typeof i.gate_required === 'boolean' ? i.gate_required : undefined,
+  };
+  normalized.category = classifyCategory(normalized);
+  normalized.severity = classifySeverity(normalized);
+  for (const key of Object.keys(normalized)) {
+    if (normalized[key] === undefined) delete normalized[key];
+  }
+  return normalized;
+}
+
+function normalizeFiles(files) {
+  if (!files) return [];
+  if (Array.isArray(files)) return files.map(String);
+  return [String(files)];
+}
+
+function stringifyField(value) {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value);
+}
+
+function normalizeVerdict(verdict, issues, decided, opts = {}) {
+  const v = String(verdict || '').toLowerCase();
+  let result;
+  if (['block', 'approve_with_fixes', 'approve'].includes(v)) {
+    result = v;
+  } else if (['request_changes', 'changes_requested', 'fix', 'gate'].includes(v)) {
+    result = deriveVerdict(
+      issues.length ? issues : [{ severity: 'high', category: 'correctness', summary: String(decided || 'changes requested') }],
+      opts,
+    );
+  } else {
+    result = deriveVerdict(issues, opts);
+  }
+
+  // 보수 강등: 명시 verdict 가 approve 류라도 high > 5 / confidence < 0.6 이면 block.
+  // codex 가 자신감 없게 approve 한 경우의 안전망.
+  if (result !== 'block') {
+    const c = severityCounts(issues);
+    if (c.high > 5)                                                   return 'block';
+    if (typeof opts.confidence === 'number' && opts.confidence < 0.6) return 'block';
+  }
+  return result;
+}
+
+export { buildPrompt as _buildPrompt, extractJson, normalizeHandoff as _normalizeHandoff };

package/scripts/agents/runners/gemini.js

@@ -0,0 +1,92 @@
+// Gemini runner: calls the local Gemini CLI subprocess.
+// Default auth is delegated to the user's local gemini/gcloud session.
+
+import { assertDelegatedCliAuth } from '../../core/auth-guard.js';
+import { resolveProviderCli } from '../../core/cli-resolver.js';
+import { withGitMutationGuard } from '../../core/git-mutation-guard.js';
+import { extractJson } from '../../core/json-extractor.js';
+import { spawnAndCollect } from '../../core/subprocess.js';
+
+export async function runGemini(args) {
+  assertDelegatedCliAuth('gemini');
+
+  const cwd = args.projectRoot || args.harnessRoot || process.cwd();
+  const trustRoots = [cwd, args.harnessRoot].filter(Boolean);
+  const bin = resolveProviderCli('gemini', { root: cwd, roots: trustRoots });
+  if (!bin) {
+    throw new Error('gemini CLI is not installed. Install/login to Gemini CLI, or use --provider=mock.');
+  }
+
+  const prompt = buildPrompt(args);
+  const cliArgs = buildCliArgs(args);
+  const stdout = await withGitMutationGuard(
+    cwd,
+    () => spawnAndCollect(bin, cliArgs, prompt, {
+      label: 'gemini',
+      timeoutMs: Number(process.env.HARNESS_GEMINI_TIMEOUT_S || 120) * 1000,
+      cwd,
+    }),
+    { label: 'gemini', allowEnvKey: 'HARNESS_GEMINI_ALLOW_WORKSPACE_MUTATION' },
+  );
+
+  return parseGeminiOutput(stdout);
+}
+
+function buildCliArgs(a) {
+  const args = [
+    '--prompt',
+    'Use the instructions provided on stdin. Return only the requested JSON.',
+    '--output-format',
+    'json',
+    '--approval-mode',
+    'plan',
+    '--skip-trust',
+  ];
+
+  const model = process.env.HARNESS_GEMINI_MODEL || a.model;
+  if (model) args.push('--model', model);
+  return args;
+}
+
+function parseGeminiOutput(stdout) {
+  const parsed = parseOuterJson(stdout);
+  if (parsed && typeof parsed.response === 'string') {
+    const responseJson = extractJson(parsed.response);
+    if (!responseJson) {
+      throw new Error('Gemini JSON wrapper did not contain handoff JSON in response. raw:\n' + parsed.response.slice(0, 500));
+    }
+    return JSON.parse(responseJson);
+  }
+
+  return parsed;
+}
+
+function parseOuterJson(stdout) {
+  const text = String(stdout || '').trim();
+  if (!text) throw new Error('Gemini response did not contain JSON. raw:\n');
+
+  try {
+    return JSON.parse(text);
+  } catch {}
+
+  const json = extractJson(text);
+  if (!json) throw new Error('Gemini response did not contain JSON. raw:\n' + text.slice(0, 500));
+  return JSON.parse(json);
+}
+
+function buildPrompt(a) {
+  return [
+    `# System: HARNESS agent "${a.agent}" stage "${a.stage}".`,
+    'Output exactly one JSON object shaped like schemas/handoff.schema.json.',
+    `Sandbox: ${a.sandbox || 'read-only'}.`,
+    'Non-interactive handoff mode: do not call tools, edit files, run shell commands, wait for approvals, or make commits.',
+    'No prose outside JSON. Korean for natural-language fields unless the task asks otherwise.',
+    '',
+    `# Task: ${a.task || '(none)'}`,
+    a.promptBody ? '## Agent Body\n' + a.promptBody : '',
+    a.context?.diff ? '## Git Diff\n```diff\n' + String(a.context.diff).slice(0, 30000) + '\n```' : '',
+    a.context?.prd ? '## PRD\n```json\n' + JSON.stringify(a.context.prd, null, 2) + '\n```' : '',
+  ].filter(Boolean).join('\n');
+}
+
+export { buildPrompt as _buildPrompt, buildCliArgs as _buildCliArgs, parseGeminiOutput as _parseGeminiOutput };