@tienne/gestalt 0.120.1 → 0.121.0

package/README.ko.md

@@ -246,6 +246,20 @@ codex plugin add gestalt@gestalt
 
 스킬은 다음 Codex 세션부터 잡혀요. 슬래시 커맨드랑 Claude Code Task 패널은 Claude Code 전용이라, Codex에서는 하려는 일을 말로 설명하면 Codex가 해당 `SKILL.md`를 읽어 진행해요.
 
+설치 후 새 세션에서 “Gestalt 상태 확인해줘” 또는 “이 프로젝트를 Codex용 Gestalt로 초기화해줘”라고 요청하면 돼요.
+MCP 초기화 때 Codex를 인식해서 실행 컨텍스트는 기본으로 `AGENTS.md`에 기록하고 에이전트 모델은 현재
+Codex 세션을 상속해요. 명시한 `client`와 모델 설정은 유지하며 `client: "both"`면 두 호스트 파일에 계속 기록해요.
+프로젝트에 Codex 설정을 남기려면 초기화 스킬에 요청하면 돼요. 스킬이 아래의 버전 고정 런처로
+`setup --client codex`를 실행해요. 코드 그래프와 Git 훅까지 설정하려면 `init --client codex`를
+실행하고 고정된 CLI가 아직 이 옵션을 지원하지 않으면 호환 절차를 적용해요.
+
+스킬은 [호스트 어댑터](./plugin/skills/_shared/host-runtime.md)로 Claude 도구 예시를 현재 Codex 도구에 맞춰 실행해요.
+CLI 검사는 [버전 고정 런처](./plugin/skills/_shared/cli-launcher.md)를 거쳐서 전역 `gestalt` 설치가 필요 없어요.
+첫 CLI 실행은 플러그인과 같은 npm 버전을 내려받을 수 있으니 Node.js >=22와 npm이 PATH에 있어야 해요.
+
+연결이 실패하면 MCP 상태와 Node/npm부터 확인해요. 호스트나 모델이 예상과 다르면 `ges_status`의 `hostClient`,
+`client`, `tierModels`를 먼저 확인해요. Claude Task 패널과 Claude 전용 훅은 Codex 실행을 막지 않아요.
+
 ---
 
 ### 옵션 5: OpenAI Codex CLI (MCP만)
@@ -593,7 +607,7 @@ ges_create_agent  →  action: "submit", sessionId: "<id>", agentContent: "..."
 
 ### 스킬
 
-Claude Code에서는 스킬마다 슬래시 커맨드로 불러요. Codex에서는 같은 스킬이 `gestalt:<이름>`이고 하려는 일을 말로 설명하면 Codex가 골라 읽어요.
+Claude Code에서는 스킬마다 슬래시 커맨드로 불러요. Codex에서는 같은 스킬이 `gestalt:<이름>`이고 하려는 일을 말로 설명하면 Codex가 골라 읽어요. 비슷한 스킬 중 뭘 써야 할지 헷갈리면 [스킬 고르기](./docs/choosing-skills.md)를 보세요.
 
 | 스킬 | 언제 쓰나요 |
 |------|-------------|
@@ -617,8 +631,13 @@ Claude Code에서는 스킬마다 슬래시 커맨드로 불러요. Codex에서
 | `/ship` | 로컬 PR로 리뷰를 수렴시킨 뒤 GitHub에 draft PR로 올리고 Copilot 리뷰까지 받아요 |
 | `/brief` | 성과 보고, 제안서, RFC, 의사결정 메모를 이해관계자가 읽을 산문으로 써요 |
 | `/presentation` | 발표 자료를 만들어요. `presentation-writer`가 콘텐츠를 쓰고 `presentation-designer`가 Reveal.js HTML로 조립해요 |
-| `/video-digest` | 유튜브 영상으로 요약 뷰어를 만들어요. 불릿마다 근거가 된 스크립트 문장이 달리고 목차와 플레이어, 재생 위치를 따라가는 스크립트가 붙어요. 마크다운으로도 내요 |
-| `/lens` | 논문 PDF나 웹 글, 팟캐스트를 같이 읽어 주는 뷰어를 만들어요. 문장마다 원문 쪽과 문단 출처가 달리고 원문 표 숫자와 어긋나는 주장에는 의심 표시가, 끝에는 검증 안 된 부분이 붙어요. 선행 연구 카드와 내 노트 연결, 원문 표로 그린, 눌러 보면 바뀌는 그림도 붙여요 |
+| `/video-digest` | 유튜브 영상이나 영상 파일로 요약 뷰어를 만들어요. 불릿마다 근거가 된 스크립트 문장이 달리고 목차와 플레이어, 재생 위치를 따라가는 스크립트가 붙어요. 마크다운으로도 내요. [영상 요약 뷰어](./docs/video-digest.md) 참고 |
+| `/lens` | 논문 PDF나 웹 글, 팟캐스트를 같이 읽어 주는 뷰어를 만들어요. 문장마다 원문 쪽과 문단 출처가 달리고 원문 표 숫자와 어긋나는 주장에는 의심 표시가, 끝에는 검증 안 된 부분이 붙어요. 선행 연구 카드와 내 노트 연결, 원문 표로 그린, 눌러 보면 바뀌는 그림도 붙여요. [읽기 렌즈](./docs/lens.md) 참고 |
+| `/research` | 경쟁사 조사부터 화면 캡처, 비교표, 판단, 열린 질문까지 한 문서로 내요. 근거 없는 칸은 채우지 않고 확인 못함으로 적어요. [경쟁사 리서치](./docs/research-pipeline.md) 참고 |
+| `/market-scan` | 같은 기능을 하는 서비스 지형을 훑어 레퍼런스 후보를 골라요. 화면 캡처와 분석은 하지 않아요 |
+| `/screen-ref` | 경쟁 서비스의 화면만 수집해요. 화면 지도를 만들고 개인정보를 가짜 값으로 바꿔 캡처하며 결제 직전에서 멈춰요. 해석은 쓰지 않아요 |
+| `/ux-research` | 모아 둔 화면을 사용자와 비즈니스 관점으로 읽고 와우 포인트와 페인 포인트를 써요. 관찰은 캡처에 연결하고 효과 예측에는 해석 표시를 붙여요 |
+| `/reverse-plan` | 경쟁 서비스의 화면이 왜 그렇게 만들어졌는지 본업에서 거꾸로 짚고 가져올 것과 안 가져올 것을 갈라요. 전부 해석으로 써요 |
 | `/explain` | 개념이나 에러, 코드를 정한 대상에게 맞춰 설명하고 `explain-check`로 판정해요 |
 | `/jira-create` | `jira-writer`로 지라 티켓을 쓰고 미리보기를 승인하면 생성해요 |
 | `/slack-send` | 슬랙 메시지를 작성자 어투로 다듬고 승인하면 보내거나 예약해요 |

package/README.md

@@ -221,6 +221,27 @@ Skills load on the next Codex session. Slash commands and the Claude Code Task
 panel are still Claude Code only — in Codex you invoke a skill by describing the
 task, and Codex reads the matching `SKILL.md`.
 
+Start a new session after installing, then ask “Check Gestalt status” or
+“Set up Gestalt for this Codex project.” The server recognizes Codex during MCP
+initialization: new projects record execution context in `AGENTS.md`, and agent
+models inherit the active Codex session by default. Explicit `client` and model
+settings still take precedence; `client: "both"` continues writing both host files.
+For a persistent Codex-only project, ask the setup skill to save `client: "codex"`.
+The skill runs `setup --client codex` through the versioned launcher below
+(or `init --client codex` for the graph and Git hook), with compatibility handling
+when the pinned CLI predates that option.
+
+Skills use the bundled [host adapter](./plugin/skills/_shared/host-runtime.md) to
+translate Claude tool examples into the available Codex tools. They run CLI
+checks through the [versioned launcher](./plugin/skills/_shared/cli-launcher.md),
+so no global `gestalt` install is needed. The first CLI call may download the
+plugin's exact npm version and needs Node.js >=22 and npm on PATH.
+
+If startup fails, check MCP status and Node/npm availability. If the recorded
+host or model is unexpected, inspect `ges_status` fields `hostClient`, `client`,
+and `tierModels` before changing project settings. Claude Task panels and hooks
+are optional host-specific features; they do not gate Codex execution.
+
 ---
 
 ### Option 5: OpenAI Codex CLI (MCP only)
@@ -629,7 +650,7 @@ The review `context-collector` uses `blastRadius()` from the Code Knowledge Grap
 
 ## Skills
 
-Each skill is a slash command in Claude Code. In Codex the same skill is `gestalt:<name>`, and Codex picks it from your description of the task.
+Each skill is a slash command in Claude Code. In Codex the same skill is `gestalt:<name>`, and Codex picks it from your description of the task. Not sure which of two similar skills to use? See [Choosing a skill](./docs/choosing-skills.md).
 
 | Skill | Use it to |
 |-------|-----------|
@@ -653,8 +674,13 @@ Each skill is a slash command in Claude Code. In Codex the same skill is `gestal
 | `/ship` | Converge review on a local PR, then open a draft GitHub PR and collect Copilot review |
 | `/brief` | Performance reports, proposals, RFCs, and decision memos written as prose for stakeholders |
 | `/presentation` | Slide decks — `presentation-writer` writes the content and `presentation-designer` builds Reveal.js HTML |
-| `/video-digest` | Turn a YouTube video into a summary viewer where every bullet cites transcript sentences, with a table of contents, player, and a script that follows playback. Also exports Markdown |
-| `/lens` | Read a paper PDF, web article, or podcast with a companion viewer. Every sentence cites the source page and paragraph, claims that disagree with the source's own tables get a doubt mark, and unverified parts are collected at the end. Adds prior-work cards, links to your own notes, and interactive figures drawn from the source tables |
+| `/video-digest` | Turn a YouTube video or a video file into a summary viewer where every bullet cites transcript sentences, with a table of contents, player, and a script that follows playback. Also exports Markdown. See [Video digest](./docs/video-digest.md) |
+| `/lens` | Read a paper PDF, web article, or podcast with a companion viewer. Every sentence cites the source page and paragraph, claims that disagree with the source's own tables get a doubt mark, and unverified parts are collected at the end. Adds prior-work cards, links to your own notes, and interactive figures drawn from the source tables. See [Reading lens](./docs/lens.md) |
+| `/research` | Competitor research in one document: sources, products, screen captures, comparison, judgment, and open questions. Cells without evidence say "unconfirmed" instead of being filled in. See [Competitor research](./docs/research-pipeline.md) |
+| `/market-scan` | Survey the landscape of services that do the same job and pick reference candidates. Stops before screen capture and analysis |
+| `/screen-ref` | Collect only the competitor's screens. Builds a screen map, captures with personal data swapped for fake values, and stops before payment. No interpretation |
+| `/ux-research` | Read collected screens from the user's and the business's point of view and write wow points and pain points. Observations link to captures and predictions carry an interpretation mark |
+| `/reverse-plan` | Work backward from the competitor's core business to why the screen was built that way, then split what to bring over from what not to. Everything is marked as interpretation |
 | `/explain` | Explain a concept, error, or code for a chosen audience, then check it with `explain-check` |
 | `/jira-create` | Draft a Jira ticket with `jira-writer` and create it after you approve the preview |
 | `/slack-send` | Draft a Slack message in the author's voice and send or schedule it after you approve |
@@ -975,6 +1001,10 @@ Claude Code (you)
 - [Getting Started](./docs/getting-started.md) — 5-minute walkthrough
 - [Configuration Reference](./docs/configuration.md) — full config options
 - [Code Knowledge Graph](./docs/code-graph.md) — static analysis and blast-radius
+- [Choosing a skill](./docs/choosing-skills.md) — which skill to use when several look alike
+- [Competitor research](./docs/research-pipeline.md) — the five research skills and the order to run them
+- [Reading lens](./docs/lens.md) — paper, article, and podcast viewer with source citations
+- [Video digest](./docs/video-digest.md) — YouTube or local video summary viewer with sourced bullets
 - [Local PR](./docs/local-pr.md) — in-repo pull requests for agent-to-agent review
 - [Architecture View](./docs/architecture-view.md) — evidence-backed architecture diagrams
 - [Design Proposals](./docs/proposals/README.md) — planned work to tighten verification from interview to evaluate

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.120.1",
+  "version": "0.121.0",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "repository": {
     "type": "git",
@@ -29,11 +29,12 @@
   "scripts": {
     "dev": "tsx bin/gestalt.ts",
     "build": "tsc -p tsconfig.build.json",
-    "postbuild": "rm -rf dist/plugin && mkdir -p dist/plugin && cp -r plugin/agents plugin/role-agents plugin/review-agents plugin/personas plugin/research-sources plugin/skills dist/plugin/ && cp -r schemas dist/ && cp package.json dist/ && chmod +x dist/bin/gestalt.js dist/bin/gestalt-hook.js && pnpm run verify:plugin && pnpm run verify:rules && pnpm run verify:rule-overlap && pnpm run verify:output-style && pnpm run verify:routing && pnpm run verify:agents",
+    "postbuild": "rm -rf dist/plugin && mkdir -p dist/plugin && cp -r plugin/agents plugin/role-agents plugin/review-agents plugin/personas plugin/research-sources plugin/skills plugin/scripts plugin/.codex-plugin dist/plugin/ && cp -r schemas dist/ && cp package.json dist/ && chmod +x dist/bin/gestalt.js dist/bin/gestalt-hook.js && pnpm run verify:plugin && pnpm run verify:rules && pnpm run verify:rule-overlap && pnpm run verify:output-style && pnpm run verify:routing && pnpm run verify:agents",
     "verify:plugin": "tsx scripts/verify-plugin-assets.ts",
     "prepublishOnly": "pnpm build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:plugin-install": "vitest run --config vitest.plugin-install.config.ts",
     "serve": "tsx bin/gestalt.ts serve",
     "bench": "tsx benchmarks/run.ts",
     "resolution-bench": "tsx benchmarks/run-resolution-benchmark.ts",
@@ -47,7 +48,7 @@
     "postversion": "pnpm run version:sync && pnpm run build:output-style",
     "verify:rules": "tsx scripts/verify-rule-refs.ts",
     "verify:rule-overlap": "tsx scripts/verify-rule-overlap.ts",
-    "gate": "pnpm typecheck && pnpm verify:rules && pnpm verify:rule-overlap && pnpm verify:routing && pnpm verify:agents && pnpm verify:skill-confusion && pnpm lint && pnpm format:check && pnpm build && pnpm test",
+    "gate": "pnpm typecheck && pnpm verify:rules && pnpm verify:rule-overlap && pnpm verify:routing && pnpm verify:agents && pnpm verify:skill-confusion && pnpm lint && pnpm format:check && pnpm build && pnpm test && pnpm test:plugin-install",
     "humanize:baseline": "tsx scripts/humanize-baseline.ts",
     "build:output-style": "tsx scripts/build-output-style.ts",
     "verify:output-style": "tsx scripts/build-output-style.ts --dry-run",

package/dist/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "gestalt",
+  "version": "0.121.0",
+  "description": "Gestalt psychology-driven AI development harness. Transforms scattered requirements into structured, validated specifications through interactive interviews.",
+  "author": {
+    "name": "tienne"
+  },
+  "homepage": "https://github.com/tienne/gestalt",
+  "repository": "https://github.com/tienne/gestalt",
+  "license": "MIT",
+  "keywords": [
+    "gestalt",
+    "requirements",
+    "specification",
+    "interview",
+    "mcp",
+    "ai-development",
+    "code-review"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./mcp.json",
+  "interface": {
+    "displayName": "Gestalt",
+    "shortDescription": "Requirements-to-spec pipeline with review and PR workflows",
+    "longDescription": "Gestalt turns vague ideas into validated specifications through Gestalt-principle interviews, then drives execution, code review, and PR authoring. Bundles workflow skills, specialist agents, and MCP tools.",
+    "developerName": "tienne",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/tienne/gestalt",
+    "defaultPrompt": [
+      "Review this PR with the Gestalt review pipeline.",
+      "Clarify these requirements into a structured spec.",
+      "Write a PR description for the current branch."
+    ]
+  }
+}

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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`은 한 에이전트의