@tienne/gestalt 0.120.1 → 0.121.0

package/plugin/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "gestalt": {
       "command": "npx",
-      "args": ["-y", "@tienne/gestalt@0.120.1", "serve"],
+      "args": ["-y", "@tienne/gestalt@0.121.0", "serve"],
       "startup_timeout_sec": 180,
       "tool_timeout_sec": 900
     }

package/plugin/review-agents/writing-reviewer/AGENT.md

@@ -53,17 +53,19 @@ git diff --word-diff=porcelain -- <파일>
 
 한 조각이 룰에 걸리는지 보려면 그 조각이 들어간 **문장 전체**를 읽어야 합니다. 조각만 떼어 보면 문장 구조로 걸리는 룰(A-18 좌향 수식, C-11 연결어미 뒤 쉼표, E-2 종결어미 반복)을 판정할 수 없습니다. 판정은 문장으로 하되 이슈로 올릴지는 그 룰에 걸린 부분이 바뀐 조각 안에 있는지로 정합니다.
 
+아래 런처 경로는 이 문서 디렉토리 기준입니다. 실행 전에 절대 경로로 풉니다. 작업 레포의 동명 파일은 사용하지 않습니다.
+
 **정적 탐지를 먼저 돌립니다.** 정규식으로 잡히는 룰은 사람이 눈으로 세는 것보다 정확합니다.
 
 ```bash
-gestalt humanize-check --before <파일> --after <파일> --register doc --json
+node "../../scripts/gestalt-cli.mjs" humanize-check --before <파일> --after <파일> --register doc --json
 ```
 
 같은 파일을 `--before`와 `--after`에 둘 다 넘기면 윤문 전후 비교가 아니라 그 파일에 남아 있는 S1 패턴을 세어 줍니다. 잡히는 룰은 21개뿐이니 나머지는 읽고 판정합니다.
 
 `--register`는 대상 문서의 성격에 맞춰 고릅니다. 문서는 `doc`, 리뷰 코멘트나 대화체는 `chat`, 보고서는 `report`입니다. `chat`에서는 몇몇 S2가 S1으로 올라갑니다. 사람은 대화에서 개념을 명사 덩어리로 뭉치지 않기 때문입니다.
 
-레포에 이 명령이 없으면 그 단계를 건너뛰고 직접 읽어 판정합니다. 없다고 리뷰를 멈추지 않습니다.
+런처를 못 찾거나 버전 해석이 실패하면 그 단계를 건너뛰고 직접 읽어 판정합니다. 건너뛴 사실을 보고합니다.
 
 ## 어휘 선택을 볼 때
 

package/plugin/role-agents/_shared/references/ai-tell-quick-rules.md

@@ -214,9 +214,10 @@
 ## 코드 검사 (자가 채점보다 위)
 
 아래 등급은 모델이 스스로 매기는 참고값이다. 실제 판단은 코드가 한다.
+런처 경로는 이 문서 디렉토리 기준이다. 실행 전에 절대 경로로 풀고 작업 레포의 동명 파일을 사용하지 않는다.
 
 ```bash
-gestalt humanize-check --before before.md --after after.md --register chat
+node "../../../scripts/gestalt-cli.mjs" humanize-check --before before.md --after after.md --register chat
 ```
 
 변경률, S1 잔존, 보호 토큰 생존, 구조 보존 4가지 측면에서 각각 측정하고 exit code로 답한다

package/plugin/role-agents/humanize-monolith/AGENT.md

@@ -74,11 +74,14 @@ S2
 
 ### 0단계 — 스캔 (룰을 좁힌다)
 
+아래 런처 경로는 이 문서 디렉토리 기준이다. 실행 전에 절대 경로로 풀고 작업 레포의 동명 파일을 사용하지 않는다.
+런처를 못 찾거나 버전 해석이 실패하면 스캔과 코드 검사를 건너뛰고 직접 읽어 판정한다. 건너뛴 사실을 보고한다.
+
 원문이 파일로 있으면 먼저 스캔을 돌린다. 말투는 산문이 `doc`, 리뷰 코멘트와 슬랙이 `chat`,
 보고서가 `report`다.
 
 ```bash
-gestalt humanize-scan --file <원문> --register <doc|chat|report>
+node "../../scripts/gestalt-cli.mjs" humanize-scan --file <원문> --register <doc|chat|report>
 ```
 
 종료 코드로도 답한다. 걸린 게 있으면 0, 어투는 깨끗한데 맞춤법만 걸리면 11, 탐지기가 가리는 범위에서 0건이면 10이다. 11이면 어투는 그대로 두고 맞춤법 절만 고쳐서 낸다.
@@ -202,7 +205,7 @@ summary에 적는다. 댈 게 없으면 그건 안 고친 것이라 원문을
 위 3단계 자가검증은 스스로 매기는 참고값이다. 원문과 윤문본이 파일로 있으면 판단은 코드에 맡긴다.
 
 ```bash
-gestalt humanize-check --before <원문> --after <윤문본> --register chat --attempt 1
+node "../../scripts/gestalt-cli.mjs" humanize-check --before <원문> --after <윤문본> --register chat --attempt 1
 ```
 
 변경률, S1 제거율, 보호 토큰 생존, 구조 보존, 신규 유입을 각각 측정하고 exit code로 답한다

package/plugin/scripts/acquisition.mjs

@@ -0,0 +1,96 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { Buffer } from 'node:buffer';
+import { setTimeout, clearTimeout } from 'node:timers';
+
+// One cancellation scope spans npm resolution, version verification and cwd cleanup.
+// A child's own signal/timeout is a failed attempt, never a user's cancellation.
+export function createAcquisition({ cwd, env }) {
+  let current;
+  let signal;
+  const cancel = (received) => {
+    signal = received;
+    current?.cancel(received);
+  };
+  const terminate = () => cancel('SIGTERM');
+  const hangup = () => cancel('SIGHUP');
+  const interrupt = () => cancel('SIGINT');
+  process.on('SIGTERM', terminate);
+  process.on('SIGHUP', hangup);
+  process.on('SIGINT', interrupt);
+
+  return {
+    get signal() {
+      return signal;
+    },
+    run(command, args, timeoutMs) {
+      return new Promise((resolveResult) => {
+        const child = spawn(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let bytes = 0;
+        let failed = false;
+        let interruptTimer;
+        let killTimer;
+        let drainTimer;
+        const stop = (received) => {
+          clearTimeout(interruptTimer);
+          child.kill(received);
+          // Give npm a chance to forward cancellation first. KILL targets only this
+          // direct child; descendants can survive if npm cannot relay the signal.
+          killTimer ??= setTimeout(() => child.kill('SIGKILL'), 5000);
+        };
+        const active = {
+          cancel(received) {
+            if (received === 'SIGINT') {
+              // Do not duplicate group INT. Any surviving child gets TERM after grace.
+              interruptTimer ??= setTimeout(() => stop('SIGTERM'), 2000);
+            } else stop(received);
+          },
+        };
+        current = active;
+        const deadline = setTimeout(() => {
+          failed = true;
+          stop('SIGTERM');
+        }, timeoutMs);
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+          bytes += Buffer.byteLength(chunk);
+          if (bytes > 64 * 1024) {
+            failed = true;
+            stop('SIGTERM');
+          } else stdout += chunk;
+        });
+        child.stderr.resume();
+        child.once('error', () => {
+          failed = true;
+        });
+        child.once('exit', () => {
+          clearTimeout(deadline);
+          clearTimeout(interruptTimer);
+          clearTimeout(killTimer);
+          if (current === active) current = undefined;
+          // Descendants can inherit both pipes after npm exits. Drain briefly, then
+          // release both handles so they cannot keep resolution open indefinitely.
+          drainTimer = setTimeout(() => {
+            child.stdout.destroy();
+            child.stderr.destroy();
+          }, 1000);
+        });
+        child.once('close', (status) => {
+          clearTimeout(deadline);
+          clearTimeout(interruptTimer);
+          clearTimeout(killTimer);
+          clearTimeout(drainTimer);
+          if (current === active) current = undefined;
+          resolveResult({ status: failed ? null : status, stdout });
+        });
+        if (signal) active.cancel(signal);
+      });
+    },
+    dispose() {
+      process.off('SIGTERM', terminate);
+      process.off('SIGHUP', hangup);
+      process.off('SIGINT', interrupt);
+    },
+  };
+}

package/plugin/scripts/gestalt-cli.mjs

@@ -0,0 +1,144 @@
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ownsPackage } from './package-owner.mjs';
+import { createAcquisition } from './acquisition.mjs';
+import { npmEnvironment } from './npm-environment.mjs';
+
+const scripts = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = resolve(scripts, '..');
+const args = process.argv.slice(2);
+const fail = (message) => {
+  process.stderr.write(`gestalt CLI: ${message}\n`);
+  process.exit(1);
+};
+
+let version;
+try {
+  version = JSON.parse(readFileSync(join(pluginRoot, '.codex-plugin/plugin.json'), 'utf8')).version;
+  if (
+    typeof version !== 'string' ||
+    !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version)
+  ) {
+    throw new Error('invalid version');
+  }
+} catch {
+  fail('cannot read the bundled plugin version; reinstall the plugin.');
+}
+if (Number(process.versions.node.split('.')[0]) < 22) fail('Node.js >=22 is required.');
+
+// A development checkout is identified by the wrapper's own location, never cwd.
+// Without tsx, use a matching compiled entry if available, then the exact npm pin.
+const checkout = resolve(pluginRoot, '..');
+let localArgs;
+let sourceTsconfig;
+try {
+  const pkg = JSON.parse(readFileSync(join(checkout, 'package.json'), 'utf8'));
+  const entry = join(checkout, 'bin/gestalt.ts');
+  if (pkg.name === '@tienne/gestalt' && pkg.version === version && existsSync(entry)) {
+    const tsx = join(checkout, 'node_modules/tsx/dist/loader.mjs');
+    // Keep the target project's tsconfig paths out of the source loader.
+    if (existsSync(tsx)) {
+      localArgs = ['--import', tsx, entry];
+      sourceTsconfig = join(checkout, 'tsconfig.json');
+    }
+  }
+  if (!localArgs && pkg.name === '@tienne/gestalt' && pkg.version === version) {
+    const compiled = [join(checkout, 'bin/gestalt.js'), join(checkout, 'dist/bin/gestalt.js')].find(
+      existsSync,
+    );
+    if (compiled) localArgs = [compiled];
+  }
+} catch {
+  // A copied plugin is deliberately independent of its containing project.
+}
+
+let bin;
+if (!localArgs) {
+  const neutral = mkdtempSync(join(tmpdir(), 'gestalt-cli-'));
+  const acquisition = createAcquisition({ cwd: neutral, env: npmEnvironment(process.env) });
+  try {
+    writeFileSync(join(neutral, 'package.json'), '{"private":true}\n');
+    for (const offline of [true, false]) {
+      if (!offline)
+        process.stderr.write(`gestalt CLI: resolving @tienne/gestalt@${version} from npm.\n`);
+      const result = await acquisition.run(
+        'npm',
+        [
+          'exec',
+          '--yes',
+          `--prefix=${neutral}`,
+          '--no-workspaces',
+          ...(offline ? ['--offline'] : []),
+          `--package=@tienne/gestalt@${version}`,
+          '--',
+          process.execPath,
+          join(scripts, 'resolve-cli.mjs'),
+          version,
+        ],
+        180_000,
+      );
+      if (acquisition.signal) break;
+      if (result.status !== 0) continue;
+      try {
+        const candidate = JSON.parse(result.stdout.trim());
+        if (typeof candidate !== 'string') continue;
+        bin = realpathSync(candidate);
+        if (!ownsPackage(bin, version)) {
+          bin = undefined;
+          continue;
+        }
+        // Do not trust the resolver process or a stale global executable.
+        const check = await acquisition.run(process.execPath, [bin, '--version'], 10_000);
+        if (acquisition.signal) break;
+        if (check.status === 0 && check.stdout.trim() === version) break;
+        bin = undefined;
+      } catch {
+        bin = undefined;
+      }
+    }
+  } finally {
+    try {
+      rmSync(neutral, { recursive: true, force: true });
+    } finally {
+      acquisition.dispose();
+    }
+  }
+  if (acquisition.signal) process.kill(process.pid, acquisition.signal);
+  if (!bin)
+    fail(
+      `could not resolve @tienne/gestalt@${version}; check npm, network access, and its native dependencies. No other version was executed.`,
+    );
+}
+
+const child = spawn(process.execPath, [...(localArgs ?? [bin]), ...args], {
+  cwd: process.cwd(),
+  stdio: 'inherit',
+  ...(sourceTsconfig ? { env: { ...process.env, TSX_TSCONFIG_PATH: sourceTsconfig } } : {}),
+});
+const terminate = () => child.kill('SIGTERM');
+const hangup = () => child.kill('SIGHUP');
+// Group Ctrl-C reaches the child: do not forward it twice. Programmatic callers
+// must use SIGTERM to cancel only this pid. Signal tests cover both delivery modes.
+const interrupt = () => {};
+process.on('SIGTERM', terminate);
+process.on('SIGHUP', hangup);
+process.on('SIGINT', interrupt);
+child.once('error', (error) => fail(error.message));
+child.once('exit', (code, signal) => {
+  process.off('SIGTERM', terminate);
+  process.off('SIGHUP', hangup);
+  process.off('SIGINT', interrupt);
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/plugin/scripts/npm-environment.mjs

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import process from 'node:process';
+import { dirname, join } from 'node:path';
+
+// Registry settings may deliberately use a provider token. Preserve referenced
+// names before filtering known credentials; native-build and network settings pass through.
+export function npmEnvironment(source) {
+  const env = { ...source };
+  const find = (name) => Object.keys(env).find((key) => key.toLowerCase() === name);
+  const get = (name) => {
+    const key = find(name);
+    return key === undefined ? undefined : env[key];
+  };
+  const referenced = new Set();
+  // Match npm's optional references and escaped dollar signs in configuration.
+  const envExpr = /(?<!\\)(\\*)\$\{([^${}?]+)(\?)?\}/g;
+  const collect = (text) => {
+    for (const match of text.matchAll(envExpr)) {
+      if (match[1].length % 2 === 0) referenced.add(match[2].toLowerCase());
+    }
+  };
+  const expand = (path) =>
+    path.replace(envExpr, (whole, escapes, key, optional) => {
+      if (escapes.length % 2) return whole.slice((escapes.length + 1) / 2);
+      const value = env[key] ?? (optional ? '' : '${' + key + '}');
+      return escapes.slice(escapes.length / 2) + value;
+    });
+  const home = get('home') ?? get('userprofile') ?? homedir();
+  const files = [
+    get('npm_config_userconfig') ?? join(home, '.npmrc'),
+    get('npm_config_globalconfig') ??
+      join(get('npm_config_prefix') ?? dirname(dirname(process.execPath)), 'etc/npmrc'),
+  ];
+  for (const file of files) {
+    try {
+      const text = readFileSync(expand(file).replace(/^~(?=[/\\])/, home), 'utf8');
+      collect(
+        text
+          .split('\n')
+          .filter((line) => !/^\s*[#;]/.test(line))
+          .join('\n'),
+      );
+    } catch {
+      // Missing/unreadable npm settings are handled by npm itself.
+    }
+  }
+  for (const [key, value] of Object.entries(env)) {
+    if (/^npm_config_/i.test(key)) collect(value);
+  }
+  for (const key of Object.keys(env)) {
+    if (/^npm_|^node_auth_token$/i.test(key) || referenced.has(key.toLowerCase())) continue;
+    if (
+      /^(ANTHROPIC_|OPENAI_|CLAUDE_CODE_OAUTH_|GEMINI_|CODEX_|XAI_|GROK_|GOOGLE_API_KEY$|AWS_ACCESS_KEY_ID$|AWS_SECRET_ACCESS_KEY$|AWS_SESSION_TOKEN$|GH_TOKEN$|GITHUB_TOKEN$)/i.test(
+        key,
+      ) ||
+      /(_API_KEY|_SECRET|_SECRET_KEY|_CLIENT_SECRET|_PASSWORD|_ACCESS_TOKEN|_AUTH_TOKEN|_BOT_TOKEN)$|^HF_TOKEN$/i.test(
+        key,
+      )
+    )
+      delete env[key];
+  }
+  return env;
+}

package/plugin/scripts/package-owner.mjs

@@ -0,0 +1,20 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// The nearest manifest owns the bin; an unrelated parent must not vouch for it.
+export function ownsPackage(bin, version) {
+  try {
+    let directory = dirname(bin);
+    while (directory !== dirname(directory)) {
+      const manifest = join(directory, 'package.json');
+      if (existsSync(manifest)) {
+        const pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+        return pkg.name === '@tienne/gestalt' && pkg.version === version;
+      }
+      directory = dirname(directory);
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}

package/plugin/scripts/resolve-cli.mjs

@@ -0,0 +1,22 @@
+import process from 'node:process';
+import { realpathSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { ownsPackage } from './package-owner.mjs';
+
+// npm exec prepends its package bin directory. Verify the owning package instead
+// of accepting a same-named executable inherited from the user's PATH.
+const expected = process.argv[2];
+for (const entry of (process.env.PATH ?? '').split(delimiter)) {
+  if (!entry) continue;
+  const candidate = join(entry, 'gestalt');
+  try {
+    const bin = realpathSync(candidate);
+    if (ownsPackage(bin, expected)) {
+      process.stdout.write(JSON.stringify(bin));
+      process.exit(0);
+    }
+  } catch {
+    // Broken PATH entries and unrelated packages do not resolve this pin.
+  }
+}
+process.exitCode = 1;

package/plugin/skills/_shared/agent-delegation.md

@@ -1,5 +1,7 @@
 # 에이전트를 서브에이전트로 위임하기 (공유 규칙)
 
+> **Codex 등 다른 호스트에서는** [`host-runtime.md`](./host-runtime.md)를 먼저 적용한다. `inherit`는 모델 인자 생략이며 Claude 별칭 폴백을 강제하지 않는다.
+
 > **현재 적용: `review`, `pr`, `brief`, `presentation`, `review-reply`, `slack-send`, `jira-create`, `ship`, `explain`, `research`, `ux-research`, `reverse-plan`.** 에이전트를 불러 쓰는 스킬은 전부 위임한다. 새 스킬이 `ges_agent get`을 메인에서 하면 그건 예외가 아니라 빠뜨린 것이다.
 
 ## 왜 필요한가

package/plugin/skills/_shared/agent-model.md

@@ -1,5 +1,7 @@
 # 에이전트 tier로 모델 고르기 (공유 규칙)
 
+> **Codex 등 다른 호스트에서는** [`host-runtime.md`](./host-runtime.md)를 먼저 적용한다. `inherit`는 모델 인자 생략이며 Claude 별칭 폴백을 강제하지 않는다.
+
 `ges_agent`의 `get`과 `list`는 둘 다 `tier`와 **해석된 `model`** 을 돌려준다. 에이전트 frontmatter의
 tier가 "이 역할이 어느 정도 모델을 필요로 하나"를 선언하고 서버가 그걸 호스트 Agent 도구가 받는
 별칭으로 옮겨준 값이다. 둘의 차이는 `systemPrompt`가 딸려오느냐뿐이다. `get`은 한 에이전트의

package/plugin/skills/_shared/cli-launcher.md

@@ -1,45 +1,56 @@
-# gestalt CLI를 어떻게 부르는지 먼저 판정한다
+# 플러그인과 같은 버전의 CLI 실행
 
-이 문서는 여러 스킬이 공유하는 규칙이다. `gestalt` CLI(`humanize-scan`, `pr`, `review-loop`, `setup` 등)를 셸로 부르는 단계에서 적용한다.
-
-## 왜 필요한가
-
-플러그인으로 설치되면 호스트가 복사해 가는 건 `plugin/` 아래뿐이다. `bin/`도 `package.json`도 `node_modules`도 그 안에 없다. 그래서 스킬 본문에 `pnpm tsx bin/gestalt.ts ...`만 적혀 있으면 게슈탈트 레포 밖에서는 그 명령이 원리상 안 돈다.
-
-그때 읽는 쪽이 하는 말이 "의존성이 안 깔려 있어서 못 돌립니다"다. 실제로는 전역 `gestalt`가 깔려 있어 돌릴 수 있는데도 스킬이 적어준 형태 하나가 막혀서 포기한다. 어투 검사처럼 **필수 검사인 단계가 이렇게 조용히 건너뛰어지면** 막으려던 문장이 그대로 나간다.
-
-그래서 호출 형태를 스킬마다 박아두지 않고 한 번 판정해서 쓴다.
-
-## 판정
-
-CLI를 처음 부르기 전에 한 번 돌린다.
+스킬 본문의 `gestalt ...` 예시는 아래 런처로 실행한다. 전역 `gestalt` 설치는 필요하지 않다.
+이 문서가 있는 디렉토리(`.../skills/_shared`)에서 두 단계 위가 플러그인 루트다.
+런처는 그 아래 `scripts/gestalt-cli.mjs`에 있다. 예를 들어 문서가 `/cache/gestalt/skills/_shared/cli-launcher.md`이면 런처는 `/cache/gestalt/scripts/gestalt-cli.mjs`다.
+현재 작업 레포의 동명 파일이나 `bin/gestalt.ts`를 찾아 실행하지 않는다.
 
 ```bash
-if gestalt --version >/dev/null 2>&1; then
-  echo "OK gestalt"
-elif pnpm tsx bin/gestalt.ts --version >/dev/null 2>&1; then
-  echo "OK pnpm"
-else
-  echo "MISSING"
-fi
+node "/플러그인/절대경로/scripts/gestalt-cli.mjs" humanize-scan --file "$scanTmp/report.md" --register report
 ```
 
-- **`OK gestalt`** — 스킬 본문의 예시를 그대로 쓴다. 본문은 전부 `gestalt ...` 형태로 적혀 있다.
-- **`OK pnpm`** — 게슈탈트 레포 안이라는 뜻이다. 그 뒤로 모든 호출의 `gestalt`를 `pnpm tsx bin/gestalt.ts`로 바꿔 쓴다.
-- **`MISSING`** — 아래 "없을 때"를 따른다.
-
-한 번 확인하고 그 뒤로는 같은 형태를 쓴다. 단계마다 다시 찌르지 않는다.
+루트 `skills` 심링크로 읽었다면 먼저 이 문서 경로를 `realpath`로 풀고 부모 경로를 계산한다.
+런처는 자신의 위치를 기준으로 다음을 수행한다.
+
+1. `.codex-plugin/plugin.json`에서 설치된 플러그인의 버전을 읽는다. 버전을 모르면 중단한다.
+2. 로컬 의존성이 있는 게슈탈트 개발 체크아웃이면 그 TypeScript 엔트리를 사용한다.
+   같은 버전의 npm 설치본 안에 빌드된 CLI가 있으면 그 엔트리를 사용한다.
+   소스만 있고 의존성이 없는 플러그인 설치본은 다음 npm 해석 단계로 진행한다.
+3. 설치된 복사본이면 npm 캐시에서 정확히 같은 `@tienne/gestalt@<version>`을 해석하고
+   캐시가 없으면 같은 버전을 다운로드한다. 패키지 이름과 버전, 실제 CLI 버전을 확인한다.
+4. 실제 명령은 원래 작업 디렉토리에서 실행하며 stdin, 인자, 종료 코드를 보존한다.
+   터미널 Ctrl-C는 자식도 함께 받으므로 중복 전달하지 않는다. 래퍼 pid만 지정해 취소할 때는 SIGTERM을 사용한다.
+   SIGTERM과 SIGHUP은 npm 실행과 버전 확인, 실제 명령에 전달하고 자식 종료를 기다린다.
+   npm 실행과 버전 확인 중에는 SIGTERM이나 SIGHUP을 보낸 뒤 5초간 자식이 끝나지 않으면 SIGKILL을 보낸다.
+   SIGKILL은 직접 실행한 프로세스 하나에만 보낸다. npm이 신호를 자식에게 넘기지 못하고 멈추면 설치 스크립트 같은 자손은 남을 수 있다.
+   이 두 단계에서 SIGINT를 받으면 SIGINT를 다시 전달하지 않고 2초 동안 자식이 스스로 끝나기를 기다린다.
+   그래도 남아 있으면 SIGTERM을 보낸다. 래퍼 pid만 받은 SIGINT도 이 경로로 정리된다.
+   취소한 뒤에는 임시 디렉토리를 지운다. 오프라인 해석이나 버전 확인이 실패하거나 시간을 넘기면 같은 버전을 온라인으로 한 번 더 시도한다.
+   온라인 시도도 실패하거나 시간을 넘기면 사용자 취소가 아닌 오류로 알린다.
+
+npm 해석은 별도의 임시 디렉토리에서 한다. 작업 레포의 로컬 패키지나 다른 버전의 전역 CLI를
+선택하지 않으며 `latest`로 떨어지지 않는다.
+npm으로 CLI 패키지를 받는 동안에는 알려진 비밀 환경 변수를 npm에 넘기지 않는다.
+모델 공급자 접두어(`ANTHROPIC_`, `OPENAI_` 등)로 시작하는 변수와 클라우드, GitHub의 인증 변수(`AWS_SECRET_ACCESS_KEY`, `GITHUB_TOKEN` 등)가 여기에 든다.
+이름이 `_API_KEY`, `_PASSWORD`, `_SECRET`, `_AUTH_TOKEN` 등으로 끝나는 변수도 대소문자 구분 없이 제외한다. 이 필터는 알려진 이름과 패턴만 검사한다.
+`NPM_*`, `NODE_AUTH_TOKEN`과 `npm_config_*`는 보존한다. 사용자 `.npmrc`와 전역 설정 파일에서 `${NAME}` 또는 `${NAME?}`으로 참조한 변수도 인증에 필요하므로 예외로 남긴다.
+사용자 설정 경로는 `npm_config_userconfig` 또는 홈의 `.npmrc`다. 전역 설정은 `npm_config_globalconfig` 또는 npm prefix의 `etc/npmrc`에서 읽는다. prefix를 지정하지 않았으면 Node 설치 경로를 기준으로 한다.
+프록시와 CA 설정은 유지하며 최종 CLI에는 원래 환경을 전달한다. 처음 실행할 때 Node.js >=22와 npm, 네트워크가 필요할 수 있다.
+셸 함수가 필요하면 명령을 문자열 변수로 합치지 말고 인자를 그대로 넘긴다.
 
-**쓰려는 하위 명령이 최근에 생긴 것이면 그 하위 명령으로 찌른다.** `--version`은 설치본이 뒤처져 하위 명령만 없는 경우를 못 잡는다. 그 상태로 라운드를 돌다 `unknown option`으로 죽으면 앞선 단계가 통째로 헛돈다.
-
-**명령을 변수에 담아 함수로 넘기지 않는다.** zsh는 인용 안 한 변수 전개에서 단어 분리를 안 해 `$cmd`가 통째로 명령 이름이 된다. 실제로 깔려 있어도 `MISSING`이 나온다. 같은 코드가 bash에서는 도는 탓에 눈으로는 안 걸린다.
-
-## 없을 때
+```bash
+gestalt() { node "/플러그인/절대경로/scripts/gestalt-cli.mjs" "$@"; }
+```
 
-`MISSING`이면 **그 단계가 필수 검사인지로 갈린다.**
+셸 함수는 `xargs`의 외부 실행 파일이 아니다. **파이프라인과 `xargs`를 포함한 모든 예시**에서도
+`gestalt`를 `node`와 런처의 절대 경로로 치환한다. 함수 선언만 하고 `xargs gestalt`를 실행하지 않는다.
 
-- **필수 검사면 멈춘다.** 어투 검사(`humanize-scan`)가 그렇다. 검사를 못 돌린 걸 통과로 읽으면 검사가 없는 것과 같다. 무엇을 못 돌렸는지와 `npm i -g @tienne/gestalt`를 함께 알리고 사용자가 그대로 진행할지 정하게 둔다.
-- **판정에 쓰는 수를 그 명령이 내면 멈춘다.** `review-loop`처럼 모든 단계가 한 명령에 매달린 자리다.
-- **그 밖에는 알리고 건너뛴다.** 없다고 스킬 전체를 막을 이유는 없다. 대신 완료 보고에 어느 단계를 안 돌렸는지 적는다.
+```bash
+find "$scanTmp" -name '*.md' -print0 | xargs -0 node "/플러그인/절대경로/scripts/gestalt-cli.mjs" humanize-scan --register chat
+```
 
-어느 쪽이든 **직접 흉내내지 않는다.** 스캔 결과를 지어내거나 룰북을 눈으로 훑어 "깨끗합니다"로 답하지 않는다 ([`tool-availability.md`](./tool-availability.md)와 같은 규칙이다).
+`humanize-scan`의 종료 코드 `10`은 검사 실행 실패가 아니라 탐지 없음이다. 그 명령의 계약대로 읽는다.
+`xargs`는 자식의 종료 코드 `10`을 그대로 전달하지 않는다. 검사 판정에는 파일별 출력의 `EXIT=` 값을 사용한다. 단일 파일처럼 파일별 표지가 없는 호출에서 종료 코드가 필요하면 `xargs` 대신 런처를 직접 실행한다.
+런처를 찾지 못했거나 버전 해석이 실패하면 필수 검사와 그 수치에 의존하는 단계는 중단하고 오류를 알린다.
+그 밖의 선택적 단계는 실행하지 못한 단계를 완료 보고에 적는다. 검사 결과를 직접 지어내거나
+다른 버전의 실행을 같은 결과로 보고하지 않는다. MCP 도구는 [`tool-availability.md`](./tool-availability.md)를 따른다.

package/plugin/skills/_shared/host-runtime.md

@@ -0,0 +1,47 @@
+# 호스트별 도구 호출
+
+스킬 본문의 `Agent`, `Explore`, `AskUserQuestion`, `TaskCreate`는 Claude Code 표기다.
+실행 전에 이 문서를 읽고 **현재 호스트가 실제로 제공한 도구**로 옮긴다. Codex에서는 이 문서가
+다른 문서의 Claude 전용 타입, 모델 필수 인자, `sonnet` 폴백 지시보다 우선한다.
+MCP 도구의 입력과 2-Call 제출 계약은 호스트가 바뀌어도 그대로다.
+
+모든 호스트에서 스킬의 `gestalt ...` 예시는 먼저 [CLI 실행 지침](./cli-launcher.md)을 읽고
+버전 고정 런처로 실행한다. 개별 스킬에 이 링크가 없어도 적용하며 파이프라인과 `xargs` 호출도 포함한다.
+
+## Codex
+
+`ges_status {}`의 `hostClient`가 `codex`이면 Codex 모델 기본값은 `inherit`다.
+`client`는 실행 컨텍스트를 기록할 파일의 선택이라 `both`일 수도 있다. 이 값을 호스트 판정과 혼동하지 않는다.
+`hostClient`가 없는 이전 서버와 연결돼 있어도 현재 호스트가 Codex이면 서버의 Claude 별칭을 그대로 모델 인자로 보내지 않는다. `fable`, `haiku`, `sonnet`, `opus`는 이때 `inherit`로 취급한다. 명시한 다른 모델 ID는 유지한다. 이전 서버에는 `ges_execute` 요청의 `client: "codex"`도 명시해 컨텍스트 기록 대상을 맞추고 플러그인 갱신을 안내한다.
+사용자가 명시한 모델 ID와 실제 도구의 지원 여부를 우선한다. Claude 모델 별칭을 GPT 모델로 추측해서 바꾸지 않는다.
+실행 태스크의 자동 `task.model`이 `haiku`, `sonnet`, `opus`이면 기존 tier 힌트다. 각각 `ges_status`의
+`tierModels.frugal`, `tierModels.standard`, `tierModels.frontier`로 해석한 뒤 아래 모델 규칙을 적용한다.
+명시적인 Codex 모델 ID는 다시 매핑하지 않는다.
+
+| 본문의 표기 | Codex에서 수행할 일 |
+|---|---|
+| `Agent`의 `gestalt:` 에이전트 타입 | [`agent-delegation.md`](./agent-delegation.md)의 Explore 폴백 프롬프트를 사용해 범용 서브에이전트 안에서 `ges_agent get`으로 페르소나를 받는다. 해당 문서의 절차대로 룰북 디렉토리를 절대 경로로 풀어 프롬프트에 직접 넣는다. 경로를 못 풀었으면 그 사실을 보고한다. `subagent_type`은 전달하지 않는다. |
+| `Explore` | 읽기 전용 조사를 위임한다. 실제 읽기 전용 타입이 없으면 파일 수정, 커밋, 외부 전송 금지를 프롬프트에 명시하고 도구로 강제된 제한이라고 말하지 않는다. |
+| `Agent.model`, `reasoningModel`, `tierModels` | `inherit`이면 모델 인자를 생략한다. 명시 모델 ID는 스폰 도구가 받는 경우에만 전달한다. |
+| `effort` | 해당 도구가 받는 `reasoning_effort` 또는 동등한 인자로 옮긴다. 지원하지 않는 인자는 보내지 않는다. |
+| `AskUserQuestion` | 현재 모드의 질문 도구가 있으면 쓰고, 없으면 일반 대화로 묻는다. 필수 답변과 승인 없이 종속 단계를 실행하지 않는다. |
+| `TaskCreate`, `TaskUpdate`, `TaskList` | 호스트의 진행 계획 도구가 있으면 쓰고, 없으면 짧은 진행 메시지로 알린다. 진행 패널 부재는 작업을 막지 않는다. |
+| `Bash`, `Read`, `Grep`, `Glob`, `Edit`, `Write` | 호스트의 셸, 파일 읽기, 검색, 패치 도구를 사용한다. 명령 인자와 쓰기 범위는 그대로 지킨다. |
+
+`spawn_agent`, `send_message`, `followup_task`, `wait_agent`가 제공되면 그 도구로 위임하고 결과를 기다린다.
+스폰 스키마가 `fork_turns: "all"`일 때 모델 재지정을 금지하면, 상속 모델은 그대로 두고
+모델이나 effort를 명시해야 할 때만 `fork_turns: "none"`으로 필수 맥락과 절대 경로를 직접 전달한다.
+이 매개변수가 없는 호스트에는 그 인자를 보내지 않는다. 특정 Codex 버전의 도구명을 필수 조건으로 삼지 않는다.
+
+스폰 도구가 명시한 모델을 거절했을 때만 아래 순서로 재시도한다.
+`ges_status.hostClient`가 `codex`인 새 서버에서는 `reasoningModelFallback`이 `inherit`가 아니면 그 값으로 한 번 재시도한다. `hostClient`가 없는 이전 서버에서는 Claude 기본 별칭이 아닌 폴백 ID만 사용한다. 그것도 거절되거나 별도 폴백 ID가 없으면 세션 상속으로 한 번 재시도하고 끝낸다. 서버 기본값인 Claude 별칭으로 재시도하지 않는다. `inherit`를 지원 모델 이름처럼 전달하지 않는다. 모델 선택을 지원하지 않는 호스트에서는
+상속으로 실행하고 완료 보고에 모델 지정이 적용되지 않았음을 적는다.
+
+서브에이전트가 없으면 메인이 `ges_agent get`으로 페르소나를 받아 직접 수행할 수 있다.
+이때 컨텍스트가 메인에 실렸음을 완료 보고에 밝힌다. **독립된 판정자가 필요한 단계**는 `doubt`, review의 3.5 `continuity-judge`, 3.7 `suggestion-verifier`다. 이 셋은 메인의 자기 검토로 대체하지 않는다. 제안 검증을 못 돌렸으면 review 지침에 따라 미실행을 알린다. 정합 심급을 못 돌렸으면 그 사실을 적고 Pass를 승인으로 게시하지 않는다. MCP 자체의 부재는
+[`tool-availability.md`](./tool-availability.md)를 따르며 도구 없이 세션이나 검사 결과를 만들지 않는다.
+
+## Claude Code와 그 밖의 호스트
+
+Claude Code는 기존 `Agent` 타입과 모델 별칭을 그대로 쓴다. `inherit`를 명시했다면 모델 인자를 생략한다.
+Grok 등 다른 호스트도 실제 제공된 도구에 맞춰 같은 의미로 옮기며 지원 여부를 모르는 도구 이름이나 모델을 만들지 않는다.

package/plugin/skills/agent/SKILL.md

@@ -22,6 +22,8 @@ outputs:
 
 # Agent Skill
 
+> **호스트별 도구와 모델 호출** → [`../_shared/host-runtime.md`](../_shared/host-runtime.md). 실행 전에 읽고 현재 호스트에 맞게 적용한다.
+
 Invoke any Gestalt Role or Review agent directly, outside the Gestalt pipeline.
 
 > **도구가 없을 때** → [`../_shared/tool-availability.md`](../_shared/tool-availability.md)

package/plugin/skills/architecture/SKILL.md

@@ -61,6 +61,8 @@ outputs:
 
 # Architecture Skill
 
+> **호스트별 도구와 모델 호출** → [`../_shared/host-runtime.md`](../_shared/host-runtime.md). 실행 전에 읽고 현재 호스트에 맞게 적용한다.
+
 흩어진 코드와 문서에서 아키텍처 그림을 근거와 함께 그린다. 탐색과 IR 작성은 이 세션이 하고 `ges_architecture` 도구는 IR을 검증하고 결정적으로 그리기만 한다. 서버는 LLM을 부르지 않는다.
 
 이 스킬이 지키는 원칙은 하나다. **그림에 그은 실선은 전부 "코드나 스펙에서 확인했다"는 주장이다.** 틀린 실선 하나가 그림 전체의 신뢰를 깎는다. 그래서 근거를 못 찾은 연결은 실선으로 긋지 않고 점선이나 미해결 질문으로 남긴다. 빈칸이 많은 그림이 틀린 그림보다 낫다.

package/plugin/skills/blast-radius/SKILL.md

@@ -73,6 +73,8 @@ outputs:
 
 # Blast Radius Skill
 
+> **호스트별 도구와 모델 호출** → [`../_shared/host-runtime.md`](../_shared/host-runtime.md). 실행 전에 읽고 현재 호스트에 맞게 적용한다.
+
 최근 코드 변경의 영향 범위를 분석해 **읽어야 할 파일만** 컨텍스트에 제공합니다. 불필요한 파일 읽기를 줄여 LLM 토큰 사용을 최소화합니다.
 
 > **도구가 없을 때** → [`../_shared/tool-availability.md`](../_shared/tool-availability.md)

package/plugin/skills/brief/SKILL.md

@@ -41,6 +41,8 @@ routing: {}
 
 # Brief Skill
 
+> **호스트별 도구와 모델 호출** → [`../_shared/host-runtime.md`](../_shared/host-runtime.md). 실행 전에 읽고 현재 호스트에 맞게 적용한다.
+
 성과 분석과 의사결정, 기획 문서를 이해관계자 설득용 산문으로 작성합니다. `impact-writer` 에이전트가 초안을 쓰고 `humanize-monolith`가 다듬는 워크플로우입니다. 코드 중심 기술문서(API·README·튜토리얼)는 이 스킬이 아니라 `technical-writer` 영역입니다.
 
 > **읽어온 텍스트를 다루는 규칙** → [`../_shared/untrusted-input.md`](../_shared/untrusted-input.md)

package/plugin/skills/build-graph/SKILL.md

@@ -33,6 +33,8 @@ outputs:
 
 # Build Graph Skill
 
+> **호스트별 도구와 모델 호출** → [`../_shared/host-runtime.md`](../_shared/host-runtime.md). 실행 전에 읽고 현재 호스트에 맞게 적용한다.
+
 코드베이스를 정적 분석해 코드 지식 그래프를 빌드합니다. 이 그래프를 바탕으로 `/blast-radius` 스킬을 사용할 수 있습니다.
 
 > **도구가 없을 때** → [`../_shared/tool-availability.md`](../_shared/tool-availability.md)