novelKR · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026
diff --git a/NOTICE b/NOTICE
@@ -19,6 +19,11 @@ under the Apache License, Version 2.0.
   apply) via git submodule `third_party/codex` at
   `6b9826e3aa83b1a5947db50f4332cb9c65f1b340` (`rust-v0.154.0`).
   The pin is recorded in docs/upstream-lock.md.
+  CodeSpace modifies one pinned crate, `codex-utils-pty`, with the
+  patch in third_party/codex-patches/ (bounded observation of an
+  exited PTY child before its reap), which is applied to the
+  submodule's files before building. Each file the patch modifies
+  carries a notice saying so.
   File-copy vendoring of a single crate is not used because the crate
   depends on other Codex workspace crates (including
   `codex-exec-server`, path utilities, and tree-sitter bindings).

diff --git a/docs/codex-reuse.md b/docs/codex-reuse.md
@@ -62,7 +62,7 @@ Current entrypoints do not embed `codex-core`, `codex-exec`, or Codex App Server
 
 ## Updates and future work
 
-All reused components currently come from the [same pinned revision](upstream-lock.md). Upstream fixes arrive only after an explicit pin update and validation; they are not automatically inherited. [Update checks](upstream-update.md) include each connected adapter, not only patch tests.
+All reused components currently come from the [same pinned revision](upstream-lock.md), and one [recorded patch](upstream-lock.md#codex-downstream-patch) to `codex-utils-pty` is applied to its files. Upstream fixes arrive only after an explicit pin update and validation; they are not automatically inherited. When the pinned revision blocks work CodeSpace needs, follow the [policy for changing Codex at a pin](upstream-patches.md). [Update checks](upstream-update.md) include each connected adapter, not only patch tests.
 
 `codex-file-search`, shell-command parsing, worktree provisioning, and a general `codex-exec-server` backend remain candidates, not connected features. Evaluate a candidate by the execution function it supplies, its build/upgrade cost, and whether model or permission authority would cross the adapter boundary. Current user-facing limitations are listed in [Agent Loop integration](agent-integration.md).
 

diff --git a/docs/index.md b/docs/index.md
@@ -17,7 +17,7 @@ Use CodeSpace as the execution layer beneath your own coding agent. Start with a
 | Understand module responsibilities | [Architecture](architecture.md) and [execution contracts](execution-substrate.md) |
 | Check permissions and isolation | [Security model](security-model.md) and [runner isolation](runner-isolation.md) |
 | Handle protocol and tool results | [Protocol compatibility](protocol-compatibility.md), [patch behavior](behavior-differences.md), [error codes](error-codes.md) |
-| Maintain Codex dependencies | [Reuse scope](codex-reuse.md), [pinned revision](upstream-lock.md), [update procedure](upstream-update.md) |
+| Maintain Codex dependencies | [Reuse scope](codex-reuse.md), [pinned revision](upstream-lock.md), [update procedure](upstream-update.md), [patch policy](upstream-patches.md) |
 | Edit or publish these guides | [Documentation maintenance](documentation.md) |
 
 The implementation defines supported behavior. A test description identifies coverage; it is not a claim that a particular installation or external account was tested. Read the execution contract returned by `workspace_info` for the workspace you actually use.
diff --git a/docs/ko/codex-reuse.md b/docs/ko/codex-reuse.md
@@ -80,7 +80,7 @@ Linux 샌드박스 도우미는 실행 파일만 제공합니다. `codespace-lin
 
 ## 업데이트와 향후 검토
 
-재사용하는 구성 요소는 현재 모두 [같은 고정 버전](upstream-lock.md)에서 가져옵니다. 업스트림 수정은 버전 갱신과 검증을 거쳐야 반영되며 자동으로 들어오지 않습니다. [업데이트 검사](upstream-update.md)는 패치뿐 아니라 연결된 모든 어댑터를 포함합니다.
+재사용하는 구성 요소는 현재 모두 [같은 고정 버전](upstream-lock.md)에서 가져오며, 그 파일에 `codex-utils-pty`의 [기록된 패치](upstream-lock.md#codex-downstream-patch) 하나를 적용합니다. 업스트림 수정은 버전 갱신과 검증을 거쳐야 반영되며 자동으로 들어오지 않습니다. 고정 버전이 CodeSpace에 필요한 작업을 막으면 [고정 버전의 Codex 수정 정책](upstream-patches.md)을 따릅니다. [업데이트 검사](upstream-update.md)는 패치뿐 아니라 연결된 모든 어댑터를 포함합니다.
 
 `codex-file-search`, 셸 명령 파싱, worktree 준비, 범용 `codex-exec-server` 백엔드는 아직 연결되지 않은 후보입니다. 도입 시 제공하는 실행 기능, 빌드·업데이트 비용, 모델이나 권한 결정 책임이 어댑터 경계를 넘는지를 검토합니다. 사용자에게 영향을 주는 현재 제약은 [Agent Loop 연동](agent-integration.md)에 정리되어 있습니다.
 

diff --git a/docs/ko/index.md b/docs/ko/index.md
@@ -21,7 +21,7 @@ CodeSpace를 직접 구성한 코딩 에이전트의 실행 계층으로 연결
 | 모듈별 책임 이해 | [아키텍처](architecture.md), [실행 계약](execution-substrate.md) |
 | 권한과 격리 조건 확인 | [보안 모델](security-model.md), [러너 격리](runner-isolation.md) |
 | 프로토콜과 도구 결과 처리 | [프로토콜 호환성](protocol-compatibility.md), [패치 동작](behavior-differences.md), [오류 코드](error-codes.md) |
-| Codex 의존성 유지보수 | [재사용 범위](codex-reuse.md), [고정 버전](upstream-lock.md), [업데이트 절차](upstream-update.md) |
+| Codex 의존성 유지보수 | [재사용 범위](codex-reuse.md), [고정 버전](upstream-lock.md), [업데이트 절차](upstream-update.md), [패치 정책](upstream-patches.md) |
 | 문서 수정과 게시 | [문서 유지보수](documentation.md) |
 
 지원 동작은 실제 구현을 기준으로 설명합니다. 테스트 안내는 검사 범위를 나타내며, 특정 설치 환경이나 외부 계정에서 검증을 마쳤다는 뜻은 아닙니다. 실제 사용할 작업 공간의 실행 조건은 `workspace_info` 응답에서 확인하세요.
diff --git a/docs/ko/operations.md b/docs/ko/operations.md
@@ -11,13 +11,15 @@ macOS 또는 Linux에서 개인용 단일 사용자 서버를 준비하는 방
 
 ## 설치
 
-Git과 CI에서 사용하는 최신 Rust stable 도구 체인을 준비하세요. 루트 manifest에는 Rust 1.88이 선언되어 있지만 Codex 어댑터 전체의 최소 빌드 버전으로 검증된 값은 아닙니다. 고정된 업스트림 소스는 Rust 1.95.0을 지정합니다. macOS에는 Xcode 명령줄 도구를 설치하세요. Linux 명령 격리에는 샌드박스 도우미, bubblewrap, 필요한 네임스페이스를 생성할 권한이 추가로 필요합니다. Docker는 별도의 [컨테이너 실험 구성](../../deploy/README.md)을 사용할 때만 필요합니다.
+Git, Python 3, CI에서 사용하는 최신 Rust stable 도구 체인을 준비하세요. 루트 manifest에는 Rust 1.88이 선언되어 있지만 Codex 어댑터 전체의 최소 빌드 버전으로 검증된 값은 아닙니다. 고정된 업스트림 소스는 Rust 1.95.0을 지정합니다. macOS에는 Xcode 명령줄 도구를 설치하세요. Linux 명령 격리에는 샌드박스 도우미, bubblewrap, 필요한 네임스페이스를 생성할 권한이 추가로 필요합니다. Docker는 별도의 [컨테이너 실험 구성](../../deploy/README.md)을 사용할 때만 필요합니다.
 
 ```bash
 git clone --recurse-submodules https://github.com/novelKR/CodeSpace.git
 cd CodeSpace
 # 이미 복제한 저장소에서도 서브모듈을 초기화합니다.
 git submodule update --init --recursive
+# CodeSpace가 기록한 Codex 패치를 적용합니다. 서브모듈을 갱신할 때마다 다시 실행합니다.
+python3 scripts/codex_patch.py apply
 cargo build --locked -p codespace-server --bin codespace-mcp --release
 cargo build --locked --manifest-path crates/patch/Cargo.toml --bin codespace-patch --release
 mkdir -p dist

diff --git a/docs/ko/upstream-lock.md b/docs/ko/upstream-lock.md
@@ -19,11 +19,33 @@
 | 태그 | `rust-v0.154.0` |
 | 커밋 | `6b9826e3aa83b1a5947db50f4332cb9c65f1b340` |
 | 경로 | `third_party/codex` |
+| 하위 패치 | 1개. 이 커밋의 파일에 적용함. [하위 패치](#codex-downstream-patch) 참고 |
 | 사용하는 구성 요소 | 패치, 런타임 worker, PTY, 파일 시스템, Linux 샌드박스·프록시 어댑터 |
 | 패치 옵션 | `PreserveLineEndings`, `follow_symlinks: false` |
 
 정확한 역할은 [연결된 구성 요소](codex-reuse.md)를 참고하세요. 패치 테스트는 선택된 동작 일치 사례를 검사하며 업스트림 전체 테스트나 Codex의 모든 동작을 검증하지는 않습니다.
 
+<a id="codex-downstream-patch"></a>
+
+## 하위 패치
+
+CodeSpace는 [고정 버전의 Codex 수정 정책](upstream-patches.md)에 따라 `codex-utils-pty`에 대한 패치 하나를 유지합니다. 서브모듈은 `openai/codex`의 위 커밋에 그대로 두고 그 파일에 패치를 적용하며, 나머지 Codex crate는 모두 태그와 같습니다. `scripts/codex_patch.py`는 이 표에서 패치 파일, 그 digest, 패치를 적용한 tree를 읽습니다.
+
+| 항목 | 값 |
+| --- | --- |
+| 패치 | `third_party/codex-patches/0001-utils-pty-pre-reap-observation.patch`, SHA-256 `6f61579830f311e3c259c0642864ea9eee3c653f12c7e838e97e9b1dd35b1fba` |
+| 패치 적용 tree | `1999937194e3a68d982be85679557f0e50fe5408` |
+| 파일 | `codex-rs/utils/pty/src`의 `observe.rs`(신규), `observe_tests.rs`(신규, 테스트 전용), `pty.rs`, `lib.rs`. 제품 코드 304줄 추가, 5줄 삭제, 테스트 9개 |
+| 기능 | spawn 전에 `observe::ExitObserver`를 등록하는 `spawn_pty_process_observed`. 자식의 단일 waiter가 회수하지 않고 종료를 보고(`WNOWAIT`를 쓴 `waitid`), 관찰자에게 그 bound 안에서 한 번의 기회를 준 뒤 전과 같이 회수하고 `Completed`, `TimedOut`, `Failed`, `Unavailable` 중 하나를 보고. 관찰자가 없으면 모든 경로가 그대로. Unix가 아닌 플랫폼은 관찰 spawn을 거부 |
+| 이유 | Codex가 루트를 회수하기 전에 관리 PTY 실행의 scope를 관찰하기 위함([CSRG-U5](devguard-integration.md#devguard-lifecycle)). 2026-10-11 소유자 결정. 계약은 [업스트림 어댑터 작업 명세](https://github.com/novelKR/DevGuard/blob/668750b4ab6ad582904c3d05ffceffa062b26243/docs/handoff/2026-09-28-cs-dg-upstream-adapter-work-spec-1.md#8-preferred-investigation-b-an-upstream-owned-bounded-pre-reap-observation-contract) 8절 |
+| CodeSpace 사용 | 아직 없음. PTY 어댑터는 여전히 `spawn_pty_process`를 호출하며, 관찰자 연결은 별도 변경에서 함 |
+| 출처 | W3 실험 B의 관찰자([DevGuard 결정 패킷 3.2절](https://github.com/novelKR/DevGuard/blob/668750b4ab6ad582904c3d05ffceffa062b26243/docs/handoff/2026-09-28-w3-decision-packet.md#32-experiment-b-backend-owned-pre-reap-observation-packet-132))를 이 릴리스의 두 Unix PTY 경로로 옮긴 것. 수정한 파일마다 CodeSpace 수정 고지가 있음(Apache-2.0 4(b)) |
+| 검증 | 패치 적용 tree에서 함. Linux x86_64: crate 테스트 36개를 30회 반복해 모두 통과. macOS: 테스트 38개를 30회 반복해 모두 통과, DevGuard `6e7e065`로 W3 실험 B의 B1-B13 통과. Linux, macOS, Windows 대상 clippy 통과 |
+| 업스트림 | Codex는 외부 pull request를 받지 않음. 기능 요청 초안만 있고 제출하지 않음 |
+| 제거 조건 | Codex 릴리스가 같은 관찰(단일 waiter, bound, 결과 보고)을 제공하고 CodeSpace가 그것으로 옮기거나, CodeSpace가 더 이상 회수 전에 PTY 실행을 관찰하지 않으면 패치를 뺌 |
+| 핀 변경 시 | 패치를 되돌리고 서브모듈을 옮긴 뒤, 후보에 패치를 다시 옮기거나 제거 조건에 따라 빼고, Linux와 macOS에서 테스트를 다시 실행하고 이 기록을 갱신 |
+| 되돌리기 | CodeSpace의 관찰자 사용을 먼저 되돌린 뒤, 패치 파일과 이 기록을 함께 되돌림 |
+
 <a id="devguard-client-pin"></a>
 
 ## DevGuard client 고정 버전
@@ -60,7 +82,8 @@ gateway([CSRG-U1](devguard-integration.md#devguard-status-connection))와 UDS wo
 ## 확인과 갱신
 
 ```bash
+python3 scripts/codex_patch.py apply
 PIN_ONLY=1 ./scripts/check-upstream-pin.sh
 ```
 
-이 명령은 서브모듈 커밋과 문서의 일치 여부만 검사합니다. `PIN_ONLY`를 생략하면 패치 테스트도 실행하지만 다른 어댑터 검증을 대신하지는 않습니다. 버전을 바꾸기 전에 [전체 업데이트 절차](upstream-update.md)를 따르세요. 배포 과정에서 `git submodule update --remote`로 최신 버전을 따라가지 않습니다.
+clone하거나 서브모듈을 갱신할 때마다 빌드 전에 [기록된 패치](#codex-downstream-patch)를 적용합니다. `scripts/validate-upstream.py`는 검증할 때마다 먼저 적용합니다. 고정 버전 검사는 서브모듈 커밋이 이 문서와 일치하는지, 서브모듈의 파일이 기록된 패치 적용 tree와 정확히 같은지만 검사합니다. `PIN_ONLY`를 생략하면 패치 테스트도 실행하지만 다른 어댑터 검증을 대신하지는 않습니다. 서브모듈을 옮기기 전에는 `python3 scripts/codex_patch.py revert`를 실행하고, 버전을 바꾸기 전에 [전체 업데이트 절차](upstream-update.md)를 따르세요. 배포 과정에서 `git submodule update --remote`로 최신 버전을 따라가지 않습니다.