@capstone-nomos/cli 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @capstone-nomos/cli
+
+NOMOS 에이전트 CLI. 내 노트북의 Claude Code를 NOMOS 서버에 연결하고, 대표가 배정한 태스크를 받아 실행합니다.
+
+```bash
+npx @capstone-nomos/cli@latest connect
+```
+
+1. 브라우저가 열리면 NOMOS 웹에서 **승인**을 누릅니다(웹에 로그인돼 있어야 합니다).
+2. 대표가 이 에이전트를 프로젝트에 배정할 때까지 기다립니다. 배정되면 자동으로 시작합니다 — 창을 켜 두세요.
+3. 태스크의 레포는 `~/.nomos/repos/<조직>/<레포>`에 자동으로 받습니다. 비공개 레포는 이 노트북의 git이 접근할 수 있어야 합니다
+   (`gh auth login` 또는 Git Credential Manager).
+
+## 필요한 것
+
+- Node.js 22 이상
+- git
+- [Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code) — 설치 후 터미널에서 `claude`를 한 번 실행해 로그인
+
+## 명령
+
+| 명령 | 하는 일 |
+|---|---|
+| `connect [--server 주소] [--name 이름]` | 로그인(필요하면) → 배정 대기 → 작업 시작. 처음이라면 이것만 |
+| `doctor` | 설치 상태 점검(git·claude·연결된 서버) |
+| `login [주소] [--connect-key]` | 로그인만. 브라우저가 없는 환경(SSH)은 `--connect-key`로 가입 때 받은 연결 키를 씁니다 |
+| `start` · `once` · `refresh` · `clean` | 폴링 실행 · 태스크 하나만 · 토큰 재발급 · 작업공간 정리 |
+
+자격 증명은 `~/.nomos/credentials`(0600), 작업공간은 `~/.nomos/workspaces/`에 둡니다.

package/dist/bridge/claude-args.js

@@ -0,0 +1,45 @@
+// 헤드리스 Claude Code를 띄울 때의 인자. 순수 함수로 둔 이유는 MCP 격리가
+// "플래그 하나 빠지면 조용히 무너지는" 종류의 설정이기 때문이다 — 테스트로 고정한다.
+// MCP 설정에 쓰는 서버 이름. 도구의 전체 이름이 여기서 파생되므로 한 곳에만 둔다.
+export const MCP_SERVER_NAME = 'nomos';
+// 서버가 노출하는 도구. Claude Code에서는 mcp__<서버명>__<도구명> 형태로 불린다.
+export const NOMOS_TOOLS = ['claim_task', 'submit_artifact', 'publish_note', 'read_notes'];
+export function allowedToolNames() {
+    return NOMOS_TOOLS.map((tool) => `mcp__${MCP_SERVER_NAME}__${tool}`);
+}
+// --strict-mcp-config가 없으면 사용자의 ~/.claude.json에 등록된 MCP 서버가 함께 로드된다.
+// GitHub MCP가 살아 있으면 에이전트가 submit_artifact를 건너뛰고 직접 push할 수 있고,
+// 그러면 제출 시점 경로 검증(V3)이 아무것도 못 막는다. 두 플래그는 항상 함께 간다.
+export function buildClaudeArgs(options) {
+    // 프롬프트는 반드시 -p의 **값**으로 준다. 맨 뒤에 위치 인자로 붙이면
+    // --allowedTools가 가변 인자라 프롬프트를 도구 이름으로 삼켜버리고,
+    // claude는 "Input must be provided…"로 죽는다 (실제로 겪었다).
+    const args = ['-p', options.prompt, '--output-format', 'stream-json', '--verbose'];
+    if (options.model)
+        args.push('--model', options.model);
+    args.push('--mcp-config', options.mcpConfigPath, '--strict-mcp-config');
+    // 헤드리스에는 권한 프롬프트에 답할 사람이 없다. 이게 없으면 모델이 도구를 고른 뒤
+    // "승인 대기"에서 멈춘다 — 도구를 못 찾는 것과 증상이 달라 헷갈리기 쉽다.
+    // 가변 인자를 마지막에 두어 뒤에 아무것도 붙지 않게 한다.
+    args.push('--allowedTools', allowedToolNames().join(','));
+    return args;
+}
+// 우리 MCP 서버 하나만 담은 설정. --mcp-config로 넘긴다.
+//
+// **토큰을 여기 넣지 않는다.** 이 파일은 Claude Code에 넘기는 설정이고, 자격 증명의 정본은
+// ~/.nomos/credentials다(0600). 예전에는 env에 평문으로 박았는데, 재발급된 토큰을 되돌려 쓸 곳이 없어
+// 매 실행이 401 한 번을 먹고 시작했다.
+//
+// workspaceDir은 submit_artifact가 push할 작업공간이다. MCP 서버의 cwd가 작업공간이라는 보장이 없으므로
+// 명시한다(경로일 뿐 비밀값이 아니다). 없으면 MCP 서버는 자기 cwd를 쓴다 — 수동 테스트용.
+export function buildMcpConfig(input) {
+    return JSON.stringify({
+        mcpServers: {
+            [MCP_SERVER_NAME]: {
+                command: input.nodePath ?? process.execPath,
+                args: [input.serverPath],
+                ...(input.workspaceDir === undefined ? {} : { env: { NOMOS_WORKSPACE_DIR: input.workspaceDir } }),
+            },
+        },
+    }, null, 2);
+}

package/dist/bridge/credentials.js

@@ -0,0 +1,38 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function credentialsDir() {
+    return path.join(os.homedir(), '.nomos');
+}
+export function credentialsPath() {
+    return path.join(credentialsDir(), 'credentials');
+}
+export function readCredentials() {
+    const file = credentialsPath();
+    if (!existsSync(file))
+        return null;
+    const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    if (!parsed.baseUrl || !parsed.accessToken || !parsed.refreshToken || !parsed.agentId) {
+        throw new Error(`${file}에 baseUrl·accessToken·refreshToken·agentId가 모두 있어야 합니다`);
+    }
+    return parsed;
+}
+// 0600으로 쓴다. Windows에서는 chmod가 사실상 무시되지만, 같은 코드가 리눅스 배포에서도 돌아야 한다.
+export function writeCredentials(credentials) {
+    mkdirSync(credentialsDir(), { recursive: true, mode: 0o700 });
+    const file = credentialsPath();
+    writeFileSync(file, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Windows에서는 실패할 수 있다. 파일 내용이 더 중요하므로 막지 않는다.
+    }
+}
+// 재발급된 access token을 파일에 되돌려 쓴다. 이게 없으면 다음 실행이 또 401로 시작한다.
+export function updateAccessToken(accessToken) {
+    const current = readCredentials();
+    if (!current)
+        return;
+    writeCredentials({ ...current, accessToken });
+}

package/dist/bridge/mcp-server.js

@@ -0,0 +1,130 @@
+// NOMOS MCP 서버. 헤드리스 Claude Code가 이 서버의 도구로만 태스크를 잡고 산출물을 낸다.
+//
+// stdout은 MCP 프로토콜(JSON-RPC) 전용이다. 로그는 반드시 stderr로만 쓴다 —
+// stdout에 한 줄이라도 섞이면 클라이언트가 프로토콜 파싱에 실패한다.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { readCredentials, updateAccessToken } from './credentials.js';
+import { NomosClient, PolicyStaleLoopError } from './nomos-client.js';
+import { pushTaskBranch } from './push.js';
+// 자격 증명은 ~/.nomos/credentials가 정본이다(0600). 환경변수는 파일이 없을 때만 쓴다
+// (테스트·일회성 실행용). 둘을 섞으면 재발급 결과가 어디에 저장되는지 흐려진다.
+function resolveCredentials() {
+    const stored = readCredentials();
+    if (stored)
+        return stored;
+    const { NOMOS_BASE_URL, NOMOS_ACCESS_TOKEN, NOMOS_REFRESH_TOKEN } = process.env;
+    if (!NOMOS_BASE_URL || !NOMOS_ACCESS_TOKEN || !NOMOS_REFRESH_TOKEN) {
+        process.stderr.write('[nomos-mcp] ~/.nomos/credentials가 없고 NOMOS_* 환경변수도 없습니다\n');
+        process.exit(1);
+    }
+    return { baseUrl: NOMOS_BASE_URL, accessToken: NOMOS_ACCESS_TOKEN, refreshToken: NOMOS_REFRESH_TOKEN };
+}
+const credentials = resolveCredentials();
+const client = new NomosClient({
+    baseUrl: credentials.baseUrl,
+    tokens: { accessToken: credentials.accessToken, refreshToken: credentials.refreshToken },
+    // 재발급은 조용히 일어난다 — 모델은 401을 보지 못하고 도구가 그냥 성공한 것으로 본다.
+    // 파일에 되돌려 써야 다음 실행이 401 없이 시작한다.
+    onTokensChanged: (tokens) => {
+        updateAccessToken(tokens.accessToken);
+        process.stderr.write('[nomos-mcp] policy_stale — 토큰 재발급 후 원 요청을 1회 재시도합니다\n');
+    },
+});
+function ok(text) {
+    return { content: [{ type: 'text', text }] };
+}
+// 도구 실패는 예외로 던지지 않고 isError로 돌려준다. 모델이 이유를 읽고 다음 행동을 고를 수 있어야 한다.
+// 다만 policy_stale 루프는 다르다 — 모델이 재시도해서 될 일이 아니므로 멈추라고 명시한다.
+async function run(fn, label) {
+    try {
+        return ok(`${label}: ${JSON.stringify(await fn())}`);
+    }
+    catch (err) {
+        if (err instanceof PolicyStaleLoopError) {
+            process.stderr.write(`[nomos-mcp] ${err.message}\n`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: '경로 규칙이 계속 바뀌고 있어 작업을 멈춥니다. 재시도하지 말고 사람에게 알리세요.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[nomos-mcp] ${label} failed: ${message}\n`);
+        return { content: [{ type: 'text', text: `${label} failed: ${message}` }], isError: true };
+    }
+}
+const server = new McpServer({ name: 'nomos', version: '0.1.0' });
+server.registerTool('claim_task', {
+    title: 'Claim a task',
+    description: 'Claim a NOMOS task before doing any work on it. You must call this and get a success result before editing any file. Fails if someone else already claimed it, if its dependencies are not DONE, or if the task belongs to another team role.',
+    inputSchema: { task_id: z.string().describe('The task id to claim') },
+}, async ({ task_id }) => run(() => client.claimTask(task_id), 'claim_task'));
+// submit_artifact가 push할 작업공간. Executor가 MCP 설정의 env로 넘긴다.
+const workspaceDir = process.env.NOMOS_WORKSPACE_DIR ?? process.cwd();
+server.registerTool('submit_artifact', {
+    title: 'Submit an artifact',
+    description: 'Submit finished work for a task you have claimed. Commit your work on the task branch first, then provide the commit sha and every path you changed. This tool pushes the task branch before submitting; if the push is refused (wrong branch, commit not on the task branch, remote has diverged) nothing is submitted and you get the reason. The server re-checks the paths against the ownership rules, so listing paths you did not change (or omitting ones you did) will be rejected or will fail verification later.',
+    inputSchema: {
+        task_id: z.string().describe('The claimed task id'),
+        commit_sha: z.string().describe('Commit sha containing the work'),
+        changed_paths: z.array(z.string()).describe('Repo-relative paths changed by this commit'),
+    },
+}, async ({ task_id, commit_sha, changed_paths }) => run(async () => {
+    // push할 브랜치와 막을 브랜치는 서버가 정한다. 모델이 넘긴 값으로 고르지 않는다.
+    const briefing = (await client.getBriefing(task_id));
+    const push = await pushTaskBranch({
+        workspaceDir,
+        commitSha: commit_sha,
+        taskBranch: briefing.task.branchName,
+        protectedBranches: [briefing.repo.defaultBranch, briefing.repo.devBranch],
+    });
+    if (!push.pushed) {
+        process.stderr.write('[nomos-mcp] origin 없음 — push 건너뜀(서버가 mirror 모드로 로컬에서 읽는다)\n');
+    }
+    // push가 실패하면(PushRefused) 여기까지 오지 않는다 — 제출하지 않고 run()이 모델에게 사유를 돌려준다.
+    const artifact = await client.submitArtifact(task_id, { commitSha: commit_sha, changedPaths: changed_paths });
+    return { ...artifact, push };
+}, 'submit_artifact'));
+server.registerTool('publish_note', {
+    title: 'Publish a handover note',
+    description: 'Record what the next person needs to know about the task you claimed: what you implemented, what you decided, a gotcha you hit, or a deviation from the spec. This is a record, not a chat message — there is no reply and no recipient. Keep each key point to one short sentence; the server rejects notes that are too long instead of truncating them. Claims about another agent belong in raise_dispute, not here.',
+    inputSchema: {
+        task_id: z.string().describe('The claimed task id'),
+        kind: z.enum(['IMPLEMENTED', 'DECIDED', 'GOTCHA', 'DEVIATION']).describe('Note kind'),
+        headline: z.string().describe('One line, 60 characters or fewer'),
+        key_points: z.array(z.string()).describe('1-5 points, each 120 characters or fewer'),
+        affects: z
+            .array(z.string())
+            .optional()
+            .describe('Paths this affects. Required for DEVIATION. May point outside your own paths'),
+        supersedes: z.string().optional().describe('Note id this one corrects'),
+    },
+}, async ({ task_id, kind, headline, key_points, affects, supersedes }) => run(() => client.publishNote(task_id, {
+    kind,
+    headline,
+    keyPoints: key_points,
+    affects: affects ?? [],
+    ...(supersedes === undefined ? {} : { supersedes }),
+}), 'publish_note'));
+server.registerTool('read_notes', {
+    title: 'Read handover notes',
+    description: 'Read handover notes for the project. Notes relevant to your task are already in your prompt, so use this only when you need more — older notes, or notes for a different feature.',
+    inputSchema: {
+        project_id: z.string().describe('Project id'),
+        spec_id: z.string().optional().describe('Only notes for this feature spec'),
+        since_seq: z.number().optional().describe('Only notes after this sequence number'),
+        limit: z.number().optional().describe('Up to 50, default 20'),
+    },
+}, async ({ project_id, spec_id, since_seq, limit }) => run(() => client.readNotes(project_id, {
+    ...(spec_id === undefined ? {} : { specId: spec_id }),
+    ...(since_seq === undefined ? {} : { sinceSeq: since_seq }),
+    ...(limit === undefined ? {} : { limit }),
+}), 'read_notes'));
+await server.connect(new StdioServerTransport());
+process.stderr.write('[nomos-mcp] ready\n');

package/dist/bridge/nomos-client.js

@@ -0,0 +1,161 @@
+// 브릿지가 NOMOS 서버를 부를 때 쓰는 클라이언트. MCP 서버가 이걸 통해 도구를 실행한다.
+//
+// 핵심 책임 하나: 401 policy_stale 처리. 경로 규칙이나 정책이 바뀌면 이미 발급된 토큰은
+// 옛 스냅샷 기준이 되어 거부된다. 그때 refresh로 재발급하고 원 요청을 **1회만** 재시도한다.
+// 재발급 후에도 stale이면 루프이므로 즉시 멈춘다 — 무한 재시도가 이 흐름에서 가장 흔한 사고다.
+// 재발급 직후에도 정책이 또 바뀐 경우. 사용자에게 알리고 멈춰야 하는 신호다.
+export class PolicyStaleLoopError extends Error {
+    constructor() {
+        super('policy changed again right after refresh; stopping instead of retrying');
+        this.name = 'PolicyStaleLoopError';
+    }
+}
+export class NomosApiError extends Error {
+    status;
+    code;
+    details;
+    // details는 메시지에도 붙인다. MCP 도구는 err.message만 모델에게 보여주므로,
+    // 여기서 빼면 NOTE_INVALID의 위반 목록이 모델에 닿지 않고 같은 요청이 반복된다.
+    constructor(status, code, message, details) {
+        super(details === undefined ? message : `${message} ${JSON.stringify(details)}`);
+        this.name = 'NomosApiError';
+        this.status = status;
+        this.code = code;
+        if (details !== undefined)
+            this.details = details;
+    }
+}
+export class NomosClient {
+    baseUrl;
+    fetchImpl;
+    onTokensChanged;
+    current;
+    // 진단용. 통합 테스트가 "정확히 한 번만 재발급했는가"를 확인한다.
+    refreshCount = 0;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.onTokensChanged = options.onTokensChanged;
+        this.current = options.tokens;
+    }
+    get tokens() {
+        return this.current;
+    }
+    async claimTask(taskId) {
+        return (await this.request('POST', `/api/tasks/${taskId}/claim`));
+    }
+    async submitArtifact(taskId, input) {
+        return (await this.request('POST', `/api/tasks/${taskId}/artifacts`, input));
+    }
+    // 브릿지 단계(V2·V4) 보고. 서버가 판정하는 V1A·V1B·V3는 여기로 보낼 수 없다 — 403이 돌아온다.
+    async reportVerification(artifactId, input) {
+        return (await this.request('POST', `/api/artifacts/${artifactId}/verifications`, input));
+    }
+    // 모델이 MCP 도구로 제출한 산출물의 id를 Executor가 찾는 경로. 최신이 앞에 온다.
+    async listArtifacts(taskId) {
+        const data = (await this.request('GET', `/api/tasks/${taskId}/artifacts`));
+        return data.artifacts;
+    }
+    async publishNote(taskId, input) {
+        return (await this.request('POST', `/api/tasks/${taskId}/notes`, input));
+    }
+    async readNotes(projectId, filter = {}) {
+        const params = new URLSearchParams();
+        if (filter.specId !== undefined)
+            params.set('spec_id', filter.specId);
+        if (filter.sinceSeq !== undefined)
+            params.set('since_seq', String(filter.sinceSeq));
+        if (filter.limit !== undefined)
+            params.set('limit', String(filter.limit));
+        const query = params.toString();
+        const path = `/api/projects/${projectId}/notes${query ? `?${query}` : ''}`;
+        const data = (await this.request('GET', path));
+        return data.notes;
+    }
+    // Executor 폴링용. 에이전트 토큰이면 서버가 자기 역할로 강제 필터한다.
+    async listTasks(projectId, filter = {}) {
+        const params = new URLSearchParams();
+        if (filter.state !== undefined)
+            params.set('state', filter.state);
+        if (filter.limit !== undefined)
+            params.set('limit', String(filter.limit));
+        const query = params.toString();
+        const data = (await this.request('GET', `/api/projects/${projectId}/tasks${query ? `?${query}` : ''}`));
+        return data.tasks;
+    }
+    // 프롬프트와 .claude/settings.json을 만드는 데 필요한 것 한 번에.
+    async getBriefing(taskId) {
+        return (await this.request('GET', `/api/tasks/${taskId}/briefing`));
+    }
+    async describeSelf() {
+        return (await this.request('GET', '/api/agents/me'));
+    }
+    async reportBranch(taskId, branchName) {
+        await this.request('PATCH', `/api/tasks/${taskId}/branch`, { branchName });
+    }
+    async request(method, path, body) {
+        const first = await this.send(method, path, body);
+        if (!needsRefresh(first))
+            return unwrap(first);
+        // 여기서부터가 재시도 경로. 재발급 → 원 요청 1회.
+        await this.refresh();
+        const second = await this.send(method, path, body);
+        // 재발급 직후에도 같은 이유로 막히면 루프다. 두 번째 재발급은 하지 않는다.
+        if (needsRefresh(second))
+            throw new PolicyStaleLoopError();
+        return unwrap(second);
+    }
+    async send(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.current.accessToken}`,
+                ...(method === 'GET' ? {} : { 'Content-Type': 'application/json' }),
+            },
+            ...(method === 'GET' ? {} : { body: JSON.stringify(body ?? {}) }),
+        });
+        return { status: res.status, body: (await res.json()) };
+    }
+    async refresh() {
+        this.refreshCount += 1;
+        const res = await this.fetchImpl(`${this.baseUrl}/api/agents/token/refresh`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refreshToken: this.current.refreshToken }),
+        });
+        const body = (await res.json());
+        if (res.status !== 200) {
+            throw toApiError({ status: res.status, body });
+        }
+        const data = body.data;
+        if (!data?.accessToken) {
+            throw new NomosApiError(res.status, 'INVALID_REFRESH_RESPONSE', 'refresh returned no access token');
+        }
+        this.current = { ...this.current, accessToken: data.accessToken };
+        this.onTokensChanged?.(this.current);
+    }
+}
+function errorOf(res) {
+    const error = res.body.error;
+    return typeof error === 'object' && error !== null ? error : {};
+}
+// 재발급으로 풀 수 있는 401인가.
+//   POLICY_STALE    경로 규칙·정책이 바뀌어 토큰이 옛 스냅샷 기준이 됐다
+//   UNAUTHENTICATED access token이 만료됐다 (1시간)
+// 둘 다 refresh 한 번으로 풀린다. 만료를 빼놓으면 Executor가 한 시간 뒤부터 조용히 죽는다 —
+// 실제로 그렇게 멈춰 있었다.
+function needsRefresh(res) {
+    if (res.status !== 401)
+        return false;
+    const code = errorOf(res).code;
+    return code === 'POLICY_STALE' || code === 'UNAUTHENTICATED';
+}
+function toApiError(res) {
+    const { code, message, details } = errorOf(res);
+    return new NomosApiError(res.status, code ?? 'UNKNOWN', message ?? 'request failed', details);
+}
+function unwrap(res) {
+    if (res.status >= 400)
+        throw toApiError(res);
+    return res.body.data ?? {};
+}

package/dist/bridge/push.js

@@ -0,0 +1,93 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+// submit_artifact가 서버에 제출하기 **전에** 태스크 브랜치를 push한다.
+//
+// 이유: 배포 서버의 V3는 GitHub 커밋 API로 diff를 읽는다. 커밋이 팀원 노트북에만 있으면 GitHub는 404를
+// 주고, 그건 "없는 커밋 = FAIL"로 적혀 retry_count가 오른다 — 에이전트 잘못이 아닌데 재시도를 잃는다.
+//
+// push는 모델이 아니라 이 도구가 한다. 모델에게 push 도구를 주면 아무 브랜치에나 쓸 수 있고,
+// 그게 GitHub MCP를 막아둔 이유(--strict-mcp-config)를 그대로 무너뜨린다. 그래서 규칙을 여기 고정한다:
+//   - 서버에 기록된 태스크 브랜치(tasks.branch_name)에만 push한다
+//   - main·dev·레포의 default_branch·dev_branch로는 절대 push하지 않는다
+//   - force push 하지 않는다 (앞선 커밋과 어긋나면 거부당하고 그대로 실패로 돌려준다)
+//   - 원격(origin)이 없는 로컬 데모 레포는 건너뛴다 — 서버가 mirror 모드로 로컬 경로에서 직접 읽는다
+// 실패하면 서버에 제출하지 않는다. 호출부가 모델에게 오류를 돌려준다.
+export class PushRefused extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PushRefused';
+    }
+}
+// 이름으로 막는 브랜치. 레포별 default_branch·dev_branch는 호출부가 더한다.
+const ALWAYS_PROTECTED = ['main', 'dev'];
+const REMOTE = 'origin';
+const PUSH_TIMEOUT_MS = 60_000;
+// 헤드리스에서 자격 증명을 묻는 프롬프트가 뜨면 도구 호출이 끝없이 멈춘다. 묻지 말고 실패하게 한다.
+const defaultGit = async (cwd, args) => {
+    const { stdout } = await exec('git', ['-C', cwd, ...args], {
+        timeout: PUSH_TIMEOUT_MS,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    return stdout.trim();
+};
+// 원격 URL에 토큰이 박혀 있으면(https://user:token@host) git 에러 메시지에 그대로 실릴 수 있다.
+// 모델에게 돌려주기 전에 지운다.
+function redact(text) {
+    return text.replace(/(\w+:\/\/)[^/@\s]+@/g, '$1***@');
+}
+function failure(err) {
+    const stderr = err.stderr;
+    const raw = typeof stderr === 'string' && stderr.trim() !== '' ? stderr : err instanceof Error ? err.message : String(err);
+    return redact(raw.trim().split('\n').slice(-3).join(' / '));
+}
+export async function pushTaskBranch(input) {
+    const git = input.git ?? defaultGit;
+    const ws = input.workspaceDir;
+    try {
+        await git(ws, ['remote', 'get-url', REMOTE]);
+    }
+    catch {
+        return { pushed: false, reason: 'no-remote' };
+    }
+    const branch = input.taskBranch;
+    if (!branch) {
+        throw new PushRefused('태스크 브랜치가 서버에 기록되지 않았다 — Executor가 작업공간을 만들 때 보고한다');
+    }
+    try {
+        await git(ws, ['check-ref-format', '--branch', branch]);
+    }
+    catch {
+        throw new PushRefused(`브랜치 이름이 올바르지 않다: ${branch}`);
+    }
+    // 대소문자만 다른 이름으로 우회하지 못하게 한다(Windows·macOS에서는 같은 브랜치로 취급될 수 있다).
+    const protectedSet = new Set([...ALWAYS_PROTECTED, ...input.protectedBranches].map((b) => b.toLowerCase()));
+    if (protectedSet.has(branch.toLowerCase())) {
+        throw new PushRefused(`${branch}에는 push하지 않는다 — 태스크 브랜치에서 작업해야 한다`);
+    }
+    let head;
+    try {
+        head = await git(ws, ['symbolic-ref', '--short', 'HEAD']);
+    }
+    catch {
+        throw new PushRefused('작업공간이 브랜치 위에 있지 않다(detached HEAD)');
+    }
+    if (head !== branch) {
+        throw new PushRefused(`작업공간이 태스크 브랜치(${branch})가 아니라 ${head}에 있다`);
+    }
+    // 제출하려는 커밋이 태스크 브랜치에 들어 있어야 push 뒤에 서버가 찾을 수 있다.
+    try {
+        await git(ws, ['merge-base', '--is-ancestor', input.commitSha, `refs/heads/${branch}`]);
+    }
+    catch {
+        throw new PushRefused(`커밋 ${input.commitSha}이 태스크 브랜치(${branch})에 없다`);
+    }
+    // 명시적 refspec. '+' 접두사가 없으므로 force가 아니다 — 원격과 어긋나면 git이 거부한다.
+    try {
+        await git(ws, ['push', '--porcelain', REMOTE, `refs/heads/${branch}:refs/heads/${branch}`]);
+    }
+    catch (err) {
+        throw new PushRefused(`push 실패: ${failure(err)}`);
+    }
+    return { pushed: true, branch };
+}