polydeukes 0.7.1 → 0.9.0

package/dist/docs/reference/packages/adapter-codex.md

@@ -0,0 +1,118 @@
+# `@polydeukes/adapter-codex`
+
+**English** · [한국어](adapter-codex.ko.md)
+
+> **The Codex install unit** — lifecycle events become adapter-owned session evidence, and
+> `PreToolUse` payloads become covenant input IR with one element per file the patch touches.
+>
+> Beta. Install it next to `polydeukes`, which it names as a `peerDependency`.
+
+<a id="ownership"></a>
+## What this package owns
+
+The boundary where Codex's vocabulary is translated away. Agent and tool literals live *here*
+by design, so that they never reach the core.
+
+| Unit | What it does |
+|---|---|
+| `pdks-codex` bin | One subcommand, `pdks-codex init`, which registers the session surface in a project |
+| `runHook` | Records lifecycle evidence, or translates one `PreToolUse` payload into the input IR and spawns the judge |
+| Session evidence | Stores timestamped human messages and completed tool calls under a SHA-256 session filename, then removes it at `SessionEnd` |
+| Payload validation | Demands every key the host's generated schema marks required, in the one spelling that host sends |
+| Patch parsing | Turns the raw patch text of an `apply_patch` call into one file change per file it touches |
+| Path rebasing | Resolves a patch path against the call's working directory and carries it relative to the project root |
+
+`runHook({ repoRoot })` is what the generated hook delegator imports. `UserPromptSubmit` and
+`PostToolUse` append strict JSONL records under `.polydeukes/codex-sessions/`; `SessionEnd`
+removes only that session's file. `PreToolUse` builds the IR with the `tools` roster and a
+`session` sourced from those records, but no synthesized `actor` or `channels`, then spawns
+`pdks covenant check --enforce block` in `repoRoot` and returns the child's exit code. The
+judging happens in that child process; this package carries no judgment logic.
+
+**This package writes no telemetry rows.** A failure before the spawn is sent to `pdks` on
+stdin, so the row that call earns is written by the one writer.
+
+<a id="apply-patch"></a>
+## Why this adapter parses text where its siblings read arguments
+
+Codex normalises every file edit that reaches the hook into a single tool name, `apply_patch`,
+and puts the patch itself in `tool_input.command` — the same field a shell call uses for its
+command line. There is no path argument to read. `Edit` and `Write` exist as matcher aliases
+you may write in `.codex/hooks.json`, but the payload always names the tool `apply_patch`, so
+a roster or a branch keyed on the aliases matches nothing that ever arrives.
+
+One patch can create, update, delete and rename files in one call. The adapter carries each as
+its own element of one IR, on one spawn: every file is judged, and any one of them blocking
+blocks the whole call. A rename contributes two elements, because it changes the path it
+leaves as well as the one it takes.
+
+<a id="consumer"></a>
+## Where the consumer touches it
+
+Two lines install the Codex session surface, run from the project root:
+
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-codex
+npx pdks-codex init
+```
+
+`pdks-codex init` resolves `polydeukes` from the project, spawns `pdks init` for the
+agent-neutral scaffold, then writes the delegator and merges its entries for `PreToolUse`,
+`UserPromptSubmit`, `PostToolUse`, and `SessionEnd` into
+`.codex/hooks.json` non-destructively — other events, other matchers and keys it does not know
+are left alone. A re-run reports each existing artifact as skipped and overwrites nothing. The
+full artifact list is in [`pdks init`](../cli/init.md#init-codex).
+
+**Writing the registration is not the end of the install.** Codex records trust against the
+hash of a hook's definition, so the generated hook is listed for review and skipped until you
+approve it with `/hooks`. This is why `init` writes a byte-identical command string on every
+run: a changed one needs approving again, and until someone does, nothing is judged.
+
+Installing this adapter beside `@polydeukes/adapter-claude-code` or
+`@polydeukes/adapter-grok` in one project can run the judge twice per call.
+
+- **The generated hook** imports `runHook` from this package. Upgrading the package upgrades
+  what runs; the hook file itself never changes.
+
+No configuration namespace of its own. The scaffold `pdks init` writes protects `.codex/hooks`
+by default, so the registration this installer creates is covered by the config it creates.
+
+<a id="limits"></a>
+## Declared limits
+
+The first four are the host's own, and no adapter can narrow them. The first is measured
+rather than documented; the next three are stated in the host's hook documentation.
+
+- **A Code Mode `exec` dispatch is not observed.** In codex-cli 0.154 the host does not emit
+  `PreToolUse` for a Code Mode `exec` call, nor for the `tools.apply_patch` and
+  `tools.exec_command` calls nested in its JavaScript
+  ([openai/codex#23411](https://github.com/openai/codex/issues/23411),
+  [#38850](https://github.com/openai/codex/issues/38850)). A hook that `/hooks` lists as
+  Active still sees nothing on that surface, and a protected path edited there leaves no
+  telemetry row. `pdks-codex init` prints this as a `note:` line.
+- **The roster, not the matcher, decides what is judged.** The adapter translates
+  `apply_patch` and `Bash`; every other name — a Code Mode name, an MCP tool, `write_stdin` —
+  is refused with exit 2 and a `blocked` runner row before the judge runs. Widening the
+  matcher in `.codex/hooks.json` to such a name blocks every call under it rather than
+  judging it, and the edit changes the trust hash, so the hook is skipped until `/hooks`
+  approves it again.
+- **`write_stdin` is not judged again.** It delivers input to a unified-exec session that
+  already passed `PreToolUse`. A shell left open for input is judged once, at the call that
+  opened it.
+- **Hosted tools do not take this path.** Web search and its kind do not run through the local
+  function-tool hooks, so they reach no covenant.
+- **The host calls its tool hooks a guardrail rather than a complete enforcement boundary.**
+  Some specialized tool paths can opt out of the default hook path.
+- **The unstable transcript is not a channel.** The payload names a transcript path, but the
+  host documents that format as unstable, so no judgment reads it. The adapter instead builds
+  `session` from `UserPromptSubmit` and `PostToolUse`. A fresh configured token, alone on the
+  first line of a human message, can release the retried protected call. If no human evidence
+  was recorded, or evidence storage failed, the recovery message directs the repair to the user
+  terminal. `actor`, `channels`, and tool success are never synthesized.
+- **A patch resolving outside the project is refused rather than judged.** Such a path has no
+  project-relative form, and an element carrying one would land in no scope — judged over
+  nothing, and passed.
+- **An unresolvable `polydeukes` leaves no row.** When the umbrella cannot be resolved from the
+  project there is no process to spawn and no log path to write to, so the hook exits `2` with
+  one line on stderr and the telemetry log gains nothing. Every other pre-spawn failure does
+  reach `pdks` and does leave a row.

package/dist/docs/reference/packages/adapter-grok.ko.md

@@ -6,7 +6,7 @@
 > 판정기가 읽는 파일 변경 증거가 함께 실립니다. 세션 표면을 프로젝트에 설치하는 것도 이
 > 패키지가 합니다.
 >
-> 알파입니다. `polydeukes`와 함께 설치하며, `polydeukes`는 이 패키지의 `peerDependency`입니다.
+> 베타입니다. `polydeukes`와 함께 설치하며, `polydeukes`는 이 패키지의 `peerDependency`입니다.
 
 <a id="ownership"></a>
 ## 담당하는 기능
@@ -41,7 +41,7 @@ Grok의 입력을 공통 형식으로 번역합니다. 에이전트와 도구의
 프로젝트 루트에서 두 줄이면 Grok 세션 표면이 설치됩니다.
 
 ```sh
-npm install --save-dev polydeukes @polydeukes/adapter-grok
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-grok
 npx pdks-grok init
 ```
 
@@ -75,3 +75,7 @@ npx pdks-grok init
   스폰할 프로세스도, 기록할 로그 경로도 없습니다. 훅은 stderr에 한 줄을 남기고 종료 코드
   `2`를 내며 텔레메트리 로그에는 아무것도 추가되지 않습니다. 스폰 전 실패 가운데 이 경우만
   그렇고, 나머지는 모두 `pdks`에 도달해 행을 남깁니다.
+- **다른 호스트는 각자의 어댑터로 설치합니다.** Claude Code는
+  `@polydeukes/adapter-claude-code`로, Codex는 `@polydeukes/adapter-codex`로 설치합니다.
+  각 패키지가 자기 위임자와 명부를 씁니다. 한 프로젝트에 세션 어댑터를 둘 이상 설치하면
+  호출마다 판정기가 여러 번 실행될 수 있습니다.

package/dist/docs/reference/packages/adapter-grok.md

@@ -6,7 +6,7 @@
 > file-change evidence the judge reads, and the package installs the session surface into a
 > project.
 >
-> Alpha. Install it next to `polydeukes`, which it names as a `peerDependency`.
+> Beta. Install it next to `polydeukes`, which it names as a `peerDependency`.
 
 <a id="ownership"></a>
 ## What this package owns
@@ -42,7 +42,7 @@ file; `run_terminal_command` carries a shell line.
 Two lines install the Grok session surface, run from the project root:
 
 ```sh
-npm install --save-dev polydeukes @polydeukes/adapter-grok
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-grok
 npx pdks-grok init
 ```
 
@@ -77,3 +77,7 @@ No configuration namespace of its own.
   project there is no process to spawn and no log path to write to, so the hook exits `2` with
   one line on stderr and the telemetry log gains nothing. Every other pre-spawn failure does
   reach `pdks` and does leave a row.
+- **Other hosts install through their own adapters.** Claude Code through
+  `@polydeukes/adapter-claude-code`, Codex through `@polydeukes/adapter-codex`. Each package
+  writes its own delegator and roster. Installing more than one session adapter in a project
+  can run the judge more than once per call.

package/dist/docs/reference/packages/core.ko.md

@@ -5,7 +5,7 @@
 > **모든 약속(covenant)이 말하는 프로토콜**입니다. 입력 IR과 판정 결과 형태, 설정 스키마,
 > 텔레메트리 수집기가 여기 있습니다.
 >
-> 알파입니다. 일반 사용자는 이 패키지를 따로 설치하거나 불러올 필요가 없습니다. 통합 패키지의 의존성으로 설치되며, 사용자 진입점은
+> 베타입니다. 일반 사용자는 이 패키지를 따로 설치하거나 불러올 필요가 없습니다. 통합 패키지의 의존성으로 설치되며, 사용자 진입점은
 > [`polydeukes`](polydeukes.ko.md)입니다.
 
 <a id="ownership"></a>

package/dist/docs/reference/packages/core.md

@@ -5,7 +5,7 @@
 > **The protocol every covenant speaks** — the input IR, the verdict shape, the config
 > schema, and the telemetry collector.
 >
-> Alpha. A transitive dependency of the umbrella: you do not install it and you do not import
+> Beta. A transitive dependency of the umbrella: you do not install it and you do not import
 > it. The consumer entry point is [`polydeukes`](polydeukes.md).
 
 <a id="ownership"></a>

package/dist/docs/reference/packages/polydeukes.ko.md

@@ -31,7 +31,8 @@ import하지 않고 peer 의존으로 선언합니다.
 | `pdks docs search <query>` | 동봉된 문서를 검색 |
 | `pdks docs show <document-id>` | 동봉된 문서 또는 절을 표시 |
 
-세션 표면 설치기는 어댑터에 있습니다. `pdks-claude-code init`과 `pdks-grok init`입니다.
+세션 표면 설치기는 어댑터에 있습니다. `pdks-claude-code init`, `pdks-grok init`,
+`pdks-codex init`입니다.
 
 <a id="surface-from-input-mode"></a>
 ### 입력 방식이 곧 표면이다
@@ -112,7 +113,7 @@ IR의 `session` 키는 다른 것을 말합니다. 호스트가 그 호출에
 | 등록 | 축 | 판정 대상 |
 |---|---|---|
 | self-mod | 도구 | 편집 도구를 통한 보호 경로 변형입니다. 호출의 증명된 변형 대상만 대조하므로, 편집 **내용** 안의 보호 경로는 언급이고 통과합니다 |
-| shell-mod | 셸 | 같은 것을 명령줄로 합니다. 보호 경로를 언급하는 명령은 첫 낱말이 읽기 전용임을 증명할 때만 통과합니다 |
+| shell-mod | 셸 | 같은 것을 명령줄로 합니다. 보호 경로를 언급하는 명령은 읽기 전용임이 증명될 때만 통과합니다. 허용 목록의 첫 낱말이나, `git ls-files`·변형·실행·실행 확인·파일 출력 동작이 없는 `find`·숫자 범위 `sed -n …p`처럼 지원하는 인자 판정형 읽기 명령이 이를 증명합니다 |
 | transcript-mod | 대화 기록 | 라이브 세션 대화 기록에 대한 쓰기입니다. 전체 경로 **등가**로 판정하고 보호 조상으로는 결코 보지 않습니다 |
 
 **낱말 여섯**이 텔레메트리 계약입니다. 판정 결과 다섯과 관측 하나입니다. `.polydeukes/roi.log`의
@@ -173,7 +174,7 @@ fail-open입니다.
 - **완전 봉쇄는 목표가 아닙니다.** 여기에 차단 목록은 없습니다. 우회 철자를 열거하는 일은
   언제나 한 걸음 뒤지므로 논리를 뒤집었습니다. 보호 경로를 언급하면 안전이 증명되지 않는
   한 차단합니다. 간접 경로 계산 같은 잔여 벡터는 차단 대상이 아니라 텔레메트리 대상입니다.
-  마찰 밸브 둘, 곧 읽기 전용 허용 목록과 TTL 증인은 둘 다 측정 가능한 흔적을 남깁니다.
+  마찰 밸브 둘, 곧 읽기 전용 증명과 TTL 증인은 둘 다 측정 가능한 흔적을 남깁니다.
 - **밸브는 판정 뒤에 확인합니다.** 실제로 차단한 판정만 증언으로 열 수 있고, 문장 중간의 토큰
   언급은 밸브를 무장시키지 않으며, AI는 자기 밸브를 결코 스스로 열 수 없습니다.
 

package/dist/docs/reference/packages/polydeukes.md

@@ -31,7 +31,8 @@ takes it as a peer dependency rather than importing it.
 | `pdks docs search <query>` | Search the bundled docs |
 | `pdks docs show <document-id>` | Show one bundled document or section |
 
-Session-surface installers live on the adapters: `pdks-claude-code init` and `pdks-grok init`.
+Session-surface installers live on the adapters: `pdks-claude-code init`, `pdks-grok init`, and
+`pdks-codex init`.
 
 <a id="surface-from-input-mode"></a>
 ### The input mode is the surface
@@ -113,7 +114,7 @@ vocabulary below applies to them unchanged.
 | Registration | Axis | Judges |
 |---|---|---|
 | self-mod | Tool | Mutations to protected paths through editing tools. Only the call's proven mutation target is compared — a protected path inside an edit's *content* is a mention and passes |
-| shell-mod | Shell | The same, through a command line. A command mentioning a protected path passes only if its leading word proves it read-only |
+| shell-mod | Shell | The same, through a command line. A command mentioning a protected path passes only with read-only proof: an allowlisted leading word, or a supported argument-sensitive reader such as `git ls-files`, `find` without mutation, execution, prompting, or file-output actions, or numeric-range `sed -n …p` |
 | transcript-mod | Transcript | Writes to the live session transcript, judged by whole-path **equality** — never as a protected ancestor |
 
 **Six words** are the telemetry contract — five verdicts and one observation. A row in
@@ -178,8 +179,8 @@ No import. The umbrella assembles the module for both surfaces.
 - **Complete containment is a non-goal.** There are no blocklists here — enumerating bypass
   spellings is always one step behind, so the logic is inverted: a mention of a protected
   path blocks unless proven safe. Residual vectors such as indirect path computation are
-  telemetry targets, not block targets. The two friction valves — the read-only allowlist
-  and the TTL witness — both leave a measurable trace.
+  telemetry targets, not block targets. The two friction valves — read-only proof and the TTL
+  witness — both leave a measurable trace.
 - **The valve stands after the verdict.** Only a judgment that actually blocked can be
   witnessed open, a mid-sentence mention of the token does not arm it, and an AI can never
   open the valve for itself.

package/dist/docs/reference/packages/sdk-ts.ko.md

@@ -5,7 +5,7 @@
 > **TypeScript에서 판정기로 가는 동사 하나**입니다. 약속(covenant) 입력 IR을
 > `pdks covenant check`에 건네고 판정 결과를 값으로 돌려받습니다.
 >
-> 알파입니다. `polydeukes` · `@polydeukes/core`와 함께 설치하며, 둘 다 이 패키지의
+> 베타입니다. `polydeukes` · `@polydeukes/core`와 함께 설치하며, 둘 다 이 패키지의
 > `peerDependencies`입니다.
 
 <a id="ownership"></a>
@@ -37,6 +37,9 @@ pnpm add @polydeukes/sdk-ts polydeukes @polydeukes/core
 <a id="verb"></a>
 ## 동사
 
+이 패키지는 ESM 전용입니다(`"type": "module"`, `import` 조건만 있고 `require`는 없음).
+호출하는 파일이 `.mjs`이거나 그 `package.json`이 `"type": "module"`을 선언해야 합니다.
+
 ```ts
 import { checkCovenant } from '@polydeukes/sdk-ts';
 
@@ -92,8 +95,8 @@ type CheckCovenantSpawnSpec = { command: string; args: string[]; cwd: string; st
 **`enforce`의 기본값은 `block`입니다.** 이것은 표면의 강제 수준이지 항목의 것이 아닙니다.
 보호 경로와 `enforce: block`을 단 항목이 호출을 멈추고, 나머지 위반은 종료 코드 0에
 `advised`로 기록됩니다. 항목 자신의 강제 수준은 다른 표면에서와 같이 느슨한 쪽이 이기도록
-조합됩니다. `@polydeukes/adapter-claude-code`와 `@polydeukes/adapter-grok`도 같은 수준으로
-판정기를 스폰합니다.
+조합됩니다. `@polydeukes/adapter-claude-code`, `@polydeukes/adapter-grok`,
+`@polydeukes/adapter-codex`도 같은 수준으로 판정기를 스폰합니다.
 
 기본 스폰은 파일 서술자를 하나도 상속하지 않습니다. 호출자가 자기 서술자를 갖지 않을 수 있고,
 상속한 stdout이 닫혀 있으면 자식이 답하기 전에 EPIPE로 죽기 때문입니다. stderr는 모아서

package/dist/docs/reference/packages/sdk-ts.md

@@ -5,7 +5,7 @@
 > **One verb from TypeScript to the judge** — hand a covenant input IR to
 > `pdks covenant check` and read the verdict back as a value.
 >
-> Alpha. Install it next to `polydeukes` and `@polydeukes/core`, which it names as
+> Beta. Install it next to `polydeukes` and `@polydeukes/core`, which it names as
 > `peerDependencies`.
 
 <a id="ownership"></a>
@@ -38,6 +38,9 @@ core supplies the `CovenantInput` type the caller fills in.
 <a id="verb"></a>
 ## The verb
 
+The package is ESM only (`"type": "module"`, an `import` condition and no `require`): the calling
+file is a `.mjs`, or its `package.json` declares `"type": "module"`.
+
 ```ts
 import { checkCovenant } from '@polydeukes/sdk-ts';
 
@@ -93,8 +96,8 @@ type CheckCovenantSpawnSpec = { command: string; args: string[]; cwd: string; st
 **`enforce` defaults to `block`.** That is the surface's level, not an entry's: protected paths
 and entries carrying `enforce: block` stop the call, and every other break is recorded
 `advised` at exit 0. An entry's own level composes with it lenient-side-wins, as on every other
-surface. `@polydeukes/adapter-claude-code` and `@polydeukes/adapter-grok` spawn the judge at
-the same level.
+surface. `@polydeukes/adapter-claude-code`, `@polydeukes/adapter-grok`, and
+`@polydeukes/adapter-codex` spawn the judge at the same level.
 
 The default spawn inherits no file descriptor. A caller may hold none of its own, and an
 inherited stdout that is closed would kill the child with EPIPE before it answered. stderr is

package/dist/docs/troubleshooting.ko.md

@@ -12,8 +12,8 @@
 프로젝트 루트 바로 아래에 `polydeukes.config.yaml`, `polydeukes.config.yml`,
 `polydeukes.config.json` 중 하나도 없으면 설정이 필요한 명령은 종료 코드 2를 반환합니다.
 Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init`, `pdks-claude-code init`,
-`pdks-grok init`로 만들 수 있습니다. 이후 `pdks explain`을 실행합니다. 설정이 없다고
-기본 정책으로 대신 실행하지는 않습니다.
+`pdks-grok init`, `pdks-codex init`로 만들 수 있습니다. 이후 `pdks explain`을 실행합니다.
+설정이 없다고 기본 정책으로 대신 실행하지는 않습니다.
 
 <a id="multiple-config"></a>
 ## 설정 파일이 여러 개일 때
@@ -34,6 +34,16 @@ Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init`,
 남겨 두었습니다. 아무도 구현하지 않은 네임스페이스도 설정으로 읽히지만 읽는 쪽이 없습니다.
 수정한 뒤 `pdks explain`에서 실제 등록 내용을 확인하세요.
 
+세션 안에서는 수정 자체가 막히지 않습니다. 설정이 로드되지 않는 동안 모든 호출은 차단되지만
+하나는 예외입니다. 대상이 설정 파일 하나뿐이고, 시작 텍스트가 디스크에 있는 파일 그대로이며,
+그 결과가 로드되는 Edit 또는 Write는 종료 코드 0으로 통과하며, `covenant-check` 라벨의
+`advised` 행 하나를 고쳐진 설정 자신의 `telemetry.logPath`에 남기고 stderr에 고친 오류를
+알립니다. 이 통과는 `--enforce` 기본 자세를 읽지 않습니다. 세션 훅은 항상 `--enforce block`으로
+실행되므로, 그 아래에서 차단되는 수정은 어디에서도 실행되지 못하기 때문입니다. 결과가 여전히
+로드되지 않는 수정은 다른 호출처럼 차단되고, 설정 파일과 다른 파일을 함께 건드리는 호출이나
+디스크의 바이트에서 시작하지 않는 증거를 실은 호출도 차단됩니다. 변경 집합 표면에는 이런 경로가
+없습니다. 설정을 고치는 커밋은 오류를 볼 수 있는 터미널에서 사람이 만드는 커밋이기 때문입니다.
+
 <a id="grok-witness"></a>
 ## Grok 증인
 
@@ -48,6 +58,25 @@ Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init`,
 
 커밋 증인은 해당 스테이징 검사만 허용합니다. 차단된 Grok 도구 호출까지 허용하지 않습니다.
 
+<a id="codex-witness"></a>
+## Codex 증인
+
+여기서도 두 문제는 구별해야 하며, 첫 번째는 원인이 다릅니다.
+
+- `pdks-codex init` 실행 뒤 훅 신뢰는 훅 정의의 해시에 묶입니다. `.codex/hooks.json`이
+  바뀌면 `/hooks`에서 승인하기 전까지 신뢰하지 않으므로, 설치기가 성공해도 실행되는 훅이
+  없을 수 있습니다. 실제 도구를 호출하고 텔레메트리를 확인하세요.
+- Codex는 대화 기록 경로를 알려 주지만 그 형식을 안정된 것으로 문서화하지 않으므로 어떤
+  판정도 읽지 않습니다. 대신 어댑터가 `UserPromptSubmit`과 `PostToolUse`를 자기 세션 증거
+  파일에 기록하고 `SessionEnd`에서 지웁니다. IR은 이 `session`을 싣되 `actor`를 합성하지
+  않습니다.
+- 의도한 차단 뒤에는 설정된 증인 토큰을 첫 줄에 단독으로 보내고 다시 시도합니다. stderr가
+  `UserPromptSubmit` 증거가 없다고 알리면 생명주기 항목 넷이 모두 승인됐는지 확인합니다.
+  그래도 증거가 없다면 토큰을 반복해도 관측되지 않은 호출을 풀 수 없으므로 본인의 터미널에서
+  작업합니다.
+
+커밋 증인은 스테이징 검사만 허용하며 Codex 세션 증인을 대신하지 않습니다.
+
 <a id="config-fault"></a>
 ## 선언을 판정으로 구성하지 못할 때
 
@@ -64,16 +93,21 @@ Git에서 원래 파일을 복원하세요. 새 프로젝트라면 `pdks init`,
 판정기를 별도로 복사해 가지고 있지 않습니다. 복구 뒤 실제 호출로 다시 확인합니다.
 텔레메트리를 불러오기 전에 실패했다면 기록이 전혀 남지 않을 수도 있습니다.
 
-세션 훅은 메시지 앞에 `covenant hook failed closed:`를, 커밋 검사는
-`covenant check failed closed:`를 붙입니다. 실제로 보게 되는 두 형태는 다음과 같습니다.
+판정기 자신이 거부하는 실패(설정 없음 · 잘못된 설정 · 빌드되지 않은 판정기)는 두 표면 모두
+`covenant check failed closed:`를 붙입니다. 훅이 `pdks covenant check`에 판정을 맡기고 그 메시지를
+그대로 전달하기 때문입니다. 판정기를 스폰하기 *전에* 실패한 경우 — 어댑터가 `polydeukes`를
+찾지 못하거나 자식이 판정 없이 종료한 경우 — 만 `covenant hook failed closed:`를 붙입니다.
+실제로 보게 되는 두 형태는 다음과 같습니다.
 
 ```text
 covenant hook failed closed: Cannot find package 'polydeukes' imported from …
 covenant check failed closed: the covenant judges could not be loaded from … — run 'pnpm build' to rebuild them: Cannot find module './self-mod.js' …
+covenant check failed closed: invalid config in polydeukes.config.yaml: … — fix polydeukes.config.yaml in one Edit or Write whose result loads; every other call stays blocked until it does
 ```
 
 첫째는 설치된 패키지가 없는 경우이고, 둘째는 소스 체크아웃에서 판정기 빌드 산출물이 없거나
-일부만 있는 경우입니다.
+일부만 있는 경우이며, 셋째는 세션 표면에서 설정이 로드되지 않는 경우로 그 줄이 설정을 고칠
+호출 하나를 알려 줍니다.
 
 <a id="reading-verdict"></a>
 ## 판정 결과 읽기

package/dist/docs/troubleshooting.md

@@ -12,8 +12,8 @@ or the judging packages, provided its own installed documentation bundle is inta
 Commands that need configuration exit 2 when none of `polydeukes.config.yaml`,
 `polydeukes.config.yml`, or `polydeukes.config.json` exists directly at the project root.
 Restore the intended file from Git, or use `pdks init` / `pdks-claude-code init` /
-`pdks-grok init` for a new project. Then run `pdks explain`. No configuration means no silent
-default policy.
+`pdks-grok init` / `pdks-codex init` for a new project. Then run `pdks explain`. No
+configuration means no silent default policy.
 
 <a id="multiple-config"></a>
 ## More than one config file
@@ -32,6 +32,18 @@ Typos such as `protectedPath:` or `adaptors:` are refused. Adapter namespace nam
 open, however: a namespace nobody implements loads without being read by anything. After repair,
 run `pdks explain` and check the assembled registrations.
 
+Inside a session the repair itself is not locked out. While the config does not load, every
+call fails closed except one: an Edit or Write whose only target is the config file, whose
+starting text is the file as it is on disk, and whose result loads. That call passes with exit
+0 and one `advised` row under the `covenant-check` label, written to the repaired config's own
+`telemetry.logPath`, and the stderr line names the fault it repaired. The pass does not read
+the `--enforce` posture: the session hook always runs with `--enforce block`, and a repair that
+blocked under it would never run anywhere. A rewrite that still does not load is blocked like
+any other call, and so is a call that touches the config together with another file, or one
+whose evidence does not start from the bytes on disk. The change-set surface has no such path:
+a commit that repairs the config is a human's commit, made from a terminal that can see the
+error.
+
 <a id="grok-witness"></a>
 ## Grok witness
 
@@ -45,6 +57,25 @@ A hook not yet loaded and an unavailable witness valve are different problems:
 
 A commit witness authorizes its staged check only. It cannot release a blocked Grok tool call.
 
+<a id="codex-witness"></a>
+## Codex witness
+
+The same two problems are distinct here, and the first has its own cause:
+
+- After `pdks-codex init`, hook trust is bound to the hash of the hook definition. A changed
+  `.codex/hooks.json` is not trusted until you approve it through `/hooks`, so an installer that
+  succeeded can still leave no hook running. Verify an actual call and its telemetry.
+- Codex names a transcript path but documents the format as unstable, so no judgment reads it.
+  The adapter records `UserPromptSubmit` and `PostToolUse` into its own session evidence file
+  and removes it at `SessionEnd`; the IR carries that `session` without synthesizing `actor`.
+- After an intentional block, send the configured witness token alone on the first line and
+  retry. If stderr says no `UserPromptSubmit` evidence was recorded, confirm all four lifecycle
+  entries are approved. If evidence is still unavailable, perform the repair from your own
+  terminal; repeating the token cannot release an unobserved call.
+
+A commit witness authorizes only its staged check; it does not substitute for the Codex session
+witness.
+
 <a id="config-fault"></a>
 ## Config-fault
 
@@ -61,16 +92,21 @@ workspace build from your own terminal. The generated hook delegates to the inst
 it is not an independent copy of the judge. Verify another real call after repair. A failure
 before telemetry can load may leave no row at all.
 
-The session hook prefixes the message with `covenant hook failed closed:` and the commit check
-with `covenant check failed closed:`. The two shapes you will see:
+A failure the judge itself refuses — a missing or invalid config, an unbuilt judge — carries
+`covenant check failed closed:` on both surfaces, because the hook delegates to
+`pdks covenant check` and passes its message through. Only a failure *before* the judge could be
+spawned — the adapter cannot find `polydeukes`, or the child exited without a verdict — carries
+`covenant hook failed closed:`. The two shapes you will see:
 
 ```text
 covenant hook failed closed: Cannot find package 'polydeukes' imported from …
 covenant check failed closed: the covenant judges could not be loaded from … — run 'pnpm build' to rebuild them: Cannot find module './self-mod.js' …
+covenant check failed closed: invalid config in polydeukes.config.yaml: … — fix polydeukes.config.yaml in one Edit or Write whose result loads; every other call stays blocked until it does
 ```
 
 The first is the installed package missing; the second is a source checkout whose judge
-build output is missing or partial.
+build output is missing or partial; the third is a config that does not load, on the session
+surface, where the line names the one call that would repair it.
 
 <a id="reading-verdict"></a>
 ## Reading a verdict

package/dist/docs/tutorials/first-judgment.ko.md

@@ -17,12 +17,13 @@ mkdir pdks-example
 cd pdks-example
 git init
 printf '{"name":"pdks-example","private":true}\n' > package.json
-pnpm add -D polydeukes @polydeukes/adapter-claude-code   # 프로젝트 의존성. 일회성 npx 실행이 아님
+pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-claude-code   # 프로젝트 의존성. 일회성 npx 실행이 아님
 pnpm exec pdks-claude-code init
 ```
 
 설치기는 각 파일을 만들었으면 `created`, 이미 있어서 보존했으면 `skipped`로 보고합니다.
-초기 설정, 훅 위임 파일, Claude Code 등록 설정, 문서 조회 안내, `discipline-draft` 스킬과
+초기 설정, 훅 위임 파일(`.claude/hooks/covenant-pretooluse.mjs`), Claude Code 등록 설정
+(`.claude/settings.json`), 문서 조회 안내(`.claude/rules/polydeukes.md`), `discipline-draft` 스킬과
 텔레메트리 제외 항목을 만듭니다. 기존 사용자 파일은 보존하고, 설정은 통째로 덮지 않고
 병합합니다.
 
@@ -73,7 +74,8 @@ tail -n 5 .polydeukes/roi.log
 
 - [프로젝트 설정](../how-to/configure-project.ko.md)에서 임시 언어 이름과 테스트 명령을
   바꿉니다.
-- Grok이나 git pre-commit 훅은 [관측 표면 연결](../how-to/connect-surfaces.ko.md)을 참고합니다.
+- Grok, Codex, git pre-commit 훅은 [관측 표면 연결](../how-to/connect-surfaces.ko.md)을
+  참고합니다.
 - [규율 작성](../how-to/write-disciplines.ko.md) 예제를 실행하고, 권고 결과를 확인한 뒤 차단
   여부를 결정합니다.
 

package/dist/docs/tutorials/first-judgment.md

@@ -17,12 +17,13 @@ mkdir pdks-example
 cd pdks-example
 git init
 printf '{"name":"pdks-example","private":true}\n' > package.json
-pnpm add -D polydeukes @polydeukes/adapter-claude-code   # project dependencies, not a one-off npx run
+pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-claude-code   # project dependencies, not a one-off npx run
 pnpm exec pdks-claude-code init
 ```
 
 The installer reports `created` or `skipped` for each artifact. It creates a starter config,
-the hook delegator, the Claude Code registration, a documentation discovery file, the
+the hook delegator (`.claude/hooks/covenant-pretooluse.mjs`), the Claude Code registration
+(`.claude/settings.json`), a documentation discovery file (`.claude/rules/polydeukes.md`), the
 `discipline-draft` skill, and a telemetry ignore entry. Existing user files are preserved;
 settings are merged rather than replaced.
 
@@ -73,7 +74,8 @@ valve is assembled. See [configuration errors](../troubleshooting.md#invalid-con
 
 - [Configure the project](../how-to/configure-project.md) to replace the placeholder language
   and test command.
-- [Connect the surfaces](../how-to/connect-surfaces.md) for Grok or a git pre-commit hook.
+- [Connect the surfaces](../how-to/connect-surfaces.md) for Grok, Codex, or a git pre-commit
+  hook.
 - [Write a discipline](../how-to/write-disciplines.md) and observe an advisory before choosing
   whether it should block.
 

package/dist/load-config.d.ts

@@ -20,6 +20,17 @@ export declare const CONFIG_FILENAMES: readonly ['polydeukes.config.yaml', 'poly
 export type LoadConfigSpec = {
     rootDir: string;
 };
+/** {@link discoverConfigPath} input — the directory the candidates are looked for in. */
+export type DiscoverConfigPathSpec = {
+    rootDir: string;
+};
+/** {@link parseConfigSource} input — the config text and the path it was discovered at. */
+export type ParseConfigSourceSpec = {
+    /** The config file's whole text. */
+    source: string;
+    /** rootDir-relative path the source came from — the self-protection entry and error context. */
+    configPath: string;
+};
 /** `LoadedConfig` — the loader's return value. */
 export type LoadedConfig = {
     /** defineConfig() resolution — protectedPaths already includes configPath */
@@ -43,3 +54,16 @@ export type LoadedConfig = {
  * protection surface, guaranteed here so no assembler has to remember.
  */
 export declare function loadConfig(spec: LoadConfigSpec): LoadedConfig;
+/**
+ * The discovery half: the rootDir-relative filename of the one candidate present, or the
+ * throw that names the zero or the collision. Exported so a caller that has to know WHICH
+ * file failed to load — the runner's config-repair branch — asks the same question the
+ * loader does rather than a second spelling of it.
+ */
+export declare function discoverConfigPath(spec: DiscoverConfigPathSpec): string;
+/**
+ * The parse-and-validate half, over a text rather than a file: parse, `$schema` strip,
+ * `defineConfig`, self-protection attach. Exported so the runner can ask whether a text a
+ * call is about to write would load, without opening any file.
+ */
+export declare function parseConfigSource(spec: ParseConfigSourceSpec): LoadedConfig;

package/dist/load-config.js

@@ -39,6 +39,17 @@ export const CONFIG_FILENAMES = [
  * protection surface, guaranteed here so no assembler has to remember.
  */
 export function loadConfig(spec) {
+    const configPath = discoverConfigPath({ rootDir: spec.rootDir });
+    const source = readFileSync(join(spec.rootDir, configPath), 'utf-8');
+    return parseConfigSource({ source, configPath });
+}
+/**
+ * The discovery half: the rootDir-relative filename of the one candidate present, or the
+ * throw that names the zero or the collision. Exported so a caller that has to know WHICH
+ * file failed to load — the runner's config-repair branch — asks the same question the
+ * loader does rather than a second spelling of it.
+ */
+export function discoverConfigPath(spec) {
     const { rootDir } = spec;
     const found = CONFIG_FILENAMES.filter((name) => existsSync(join(rootDir, name)));
     if (found.length === 0) {
@@ -47,8 +58,15 @@ export function loadConfig(spec) {
     if (found.length > 1) {
         throw new Error(`ambiguous Polydeukes config in ${rootDir} — found ${found.join(' and ')}; keep exactly one`);
     }
-    const configPath = found[0];
-    const source = readFileSync(join(rootDir, configPath), 'utf-8');
+    return found[0];
+}
+/**
+ * The parse-and-validate half, over a text rather than a file: parse, `$schema` strip,
+ * `defineConfig`, self-protection attach. Exported so the runner can ask whether a text a
+ * call is about to write would load, without opening any file.
+ */
+export function parseConfigSource(spec) {
+    const { source, configPath } = spec;
     // Default core schema — custom tags stay unresolved and surface as errors or
     // warnings depending on version; both escalate to a throw (config-as-data:
     // uncomputable, so it cannot lie).

package/dist/scaffold-project.js

@@ -50,7 +50,8 @@ languages:
 # The protection list. A tool call whose proven target is one of these paths is blocked, and
 # so is a shell command that mentions one without a read-only head.
 #
-#   .claude/hooks, .claude/settings.json, .grok/hooks — the gate definitions themselves.
+#   .claude/hooks, .claude/settings.json, .grok/hooks, .codex/hooks — the gate definitions
+#     themselves.
 #     Editing them does not evade a judgment, it removes the judgment; the session surface
 #     is the only layer that can watch it happen.
 #
@@ -62,6 +63,7 @@ protectedPaths:
   - '.claude/hooks'
   - '.claude/settings.json'
   - '.grok/hooks'
+  - '.codex/hooks'
 
 # The time-boxed witness — the human valve on a blocked verdict. A human types this token so
 # it stands alone on a message's FIRST line, the window holds for ttlMinutes, then blocking

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "polydeukes",
-  "version": "0.7.1",
-  "description": "A development discipline framework for building alongside an AI coding partner — deterministic covenants, a verifiable work ledger, local memory, and adversarial verification. Alpha.",
+  "version": "0.9.0",
+  "description": "A development discipline framework for building alongside an AI coding partner — deterministic covenants, a verifiable work ledger, local memory, and adversarial verification. Beta.",
+  "author": "huskyhoochu <dfg1499@gmail.com>",
   "keywords": [
     "harness",
     "guard",
@@ -43,7 +44,7 @@
   },
   "dependencies": {
     "yaml": "2.9.0",
-    "@polydeukes/core": "^0.7.1"
+    "@polydeukes/core": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",