Skip to content

docs: 서브프로세스 서버 결정 정정 — v2.4.1 설치본에서 여전히 미해소 #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BoxLogoDev merged 1 commit into from
Aug 20, 2026
Merged

docs: 서브프로세스 서버 결정 정정 — v2.4.1 설치본에서 여전히 미해소 #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 23 additions & 12 deletions STATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,24 +20,35 @@ v2.4.0 이 npm 에 라이브인 상태에서, 데스크톱(Electron) 쪽 미완
지시서도 정리했다: `AGENTS.md` 가 정본이 되고 `CLAUDE.md`·`.windsurfrules` 는 포인터로 축소.
그 여파로 규칙을 코드로 읽던 3곳(eval 하니스·MCP 리소스·데스크톱 자산 복사)을 함께 정렬했다.

**릴리스 파이프라인이 두 번 막혔다가 뚫렸다** (PR #45, #47). 둘 다 "로컬은 통과, CI 만 실패" 형태였다 —
`build-win.ps1` 이 BOM 없는 UTF-8 이라 영어 로케일 러너에서만 파서가 깨졌고,
`bun install --ignore-scripts` 가 `@vscode/ripgrep`·`electron` 의 바이너리 postinstall 을 건너뛰어
설치 시점이 아니라 빌드 도중에 엉뚱한 메시지로 터졌다. 이 캐스케이드 전체는
`~/.claude/.../memory/sapstack-release-cascade.md` 에 남겼다.
**릴리스 파이프라인을 네 번에 걸쳐 뚫었다** (PR #45, #47, #48, #49). 데스크톱 잡이 추가된 뒤
이 파이프라인이 끝까지 간 적이 한 번도 없었고, 결함이 **순차적으로만** 드러났다 —
앞의 것을 고쳐야 다음 것이 보인다:

1. `build-win.ps1` 이 BOM 없는 UTF-8 → 영어 로케일 러너에서만 파서가 깨짐 (#45)
2. `bun install --ignore-scripts` 가 `@vscode/ripgrep`·`electron` 바이너리 postinstall 을 건너뜀 (#47)
3. `electron-builder` 가 태그 푸시에서 스스로 업로드하려다 `GH_TOKEN` 요구 (#48)
4. `npm publish` 실패가 `Create GitHub Release` 를 skip 시켜 데스크톱 배포까지 막음 (#49)

네 개 다 "로컬은 통과, CI 만 실패" 형태다. 전체 캐스케이드는
`~/.claude/.../memory/sapstack-release-cascade.md`, 4번의 판단 근거는
`decisions/active/2026-08-19-workflow-owns-release-upload.md` 에 있다.

## 열린 것

| 항목 | 막힌 이유 | 다음 행동 |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **🔴 설치본에 pi-agent-server 가 없다 — 로컬 채팅 전면 불가** | 빌드가 `packages/*/dist` 를 `dist/resources/` 로 복사하지 않았다. 설치본 실측으로 `pi-agent-server`·`llama` 부재 확인. 사용자 화면에서 `piServerPath not configured` 재현됨 | **소스는 수리 완료**(`electron-build-resources.ts` 가 복사 + 누락 시 빌드 실패). **새 릴리스를 만들어야 실제 해소된다** — 설치본은 수리 전 빌드 |
| **로컬 LLM 실기기 검증** | 위 릴리스 후에만 의미 있다 | 새 빌드 설치 → 모델팩을 `~/.sapstack/models/` 에 넣고 채팅 1턴 |
| GGUF 가중치 미번들 | 라이선스·용량 문제로 설치파일에 못 넣음 | 운영자가 USB 반입. 권장 모델팩 결정 필요 |
| Qwen3 8B "권장" 판정 보류 | 개발 머신 실측 0.75 tok/s — 타깃 사양(16GB 노트북) 미실측 | 실기기 측정 후 문서의 "장비에 따라 선택" 문구 확정 |
| 항목 | 막힌 이유 | 다음 행동 |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **🔴 설치본에 pi-agent-server 가 없다 — 로컬 채팅 전면 불가 (v2.4.1 에서도 미해소)** | 수리를 `scripts/electron-build-resources.ts` 에 넣었는데 **`build-win.ps1` 은 그걸 부르지 않는다** — 조각 빌드 + `copy-assets.ts`(정적 자산만)만 돈다. 2.4.1 설치본 실측으로 재확인. 게다가 `pi-agent-server` 는 로컬 빌드 자체가 안 된다(`@aws-crypto/crc32` 미해석, 루트 `.bun` 스토어 누락) | ① 클린 체크아웃에서 `bun install` → `bun run server:build:subprocess` 통과 여부 확인 → ② 통과하면 `build-win.ps1` 에 `server:build:subprocess` + `electron:build:resources` 추가. 검증 전 워크플로에 넣지 말 것 |
| **로컬 LLM 실기기 검증** | 위 항목이 먼저다. 2.4.1 설치본으로는 여전히 못 한다 | 서브프로세스 서버가 실린 빌드가 나온 뒤 → 모델팩을 `~/.sapstack/models/` 에 넣고 채팅 1턴 |
| **🟡 npm 토큰 만료 — MCP 2.4.1 미발행** | `Publish MCP to npm` 이 `E404 PUT` 로 실패. 패키지는 존재하므로(2.4.0) 스코프가 아니라 토큰 문제 — npm 은 권한 부족에도 404 를 준다 | **사용자 조치**: npm Automation 토큰 재발급 → `NPM_TOKEN` secret 갱신 → 워크플로 rerun. 미발행 버전이라 같은 태그 재사용 가능 |
| GGUF 가중치 미번들 | 라이선스·용량 문제로 설치파일에 못 넣음 | 운영자가 USB 반입. 권장 모델팩 결정 필요 |
| Qwen3 8B "권장" 판정 보류 | 개발 머신 실측 0.75 tok/s — 타깃 사양(16GB 노트북) 미실측 | 실기기 측정 후 문서의 "장비에 따라 선택" 문구 확정 |

## 다음 한 걸음

**실기기에서 로컬 LLM 채팅 1턴.** 데스크톱의 핵심 판매 포인트인데 한 번도 실제로 돈 적이 없다.
**클린 체크아웃에서 `bun install` → `bun run server:build:subprocess` 가 통과하는지 확인.**
이 한 줄이 갈림길이다 — 통과하면 로컬 스토어 오염이라 `build-win.ps1` 만 고치면 되고,
실패하면 의존성 해석 자체의 결함이라 별도 조사가 필요하다. 데스크톱의 핵심 판매 포인트인
로컬 LLM 채팅이 여기에 걸려 있고, 아직 한 번도 실제로 돈 적이 없다.

## 건드리면 안 되는 것

Expand Down
67 changes: 64 additions & 3 deletions decisions/active/2026-08-19-subprocess-servers-must-be-copied.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,68 @@ Error: piServerPath not configured. Cannot spawn Pi subprocess.
- 서브프로세스 서버를 단일 바이너리로 번들하게 되면 이 복사 단계가 불필요해진다
- electron-builder 가 0건 매치 glob 을 오류로 처리하게 되면 검증 위치를 옮길 수 있다

## 남은 확인
## ⚠️ 정정 (2026-08-20) — 이 결정은 아직 **효력이 없다**

**이 수정은 소스에만 반영됐다.** 사용자의 설치본은 수정 전 빌드라 여전히 결함이 있다 —
새 릴리스를 만들어 자동 업데이트로 배포해야 실제로 해소된다.
v2.4.1 을 릴리스하고 설치본을 실측한 결과, `dist/resources/` 에 `pi-agent-server` 와
`session-mcp-server` 가 **여전히 없다**. `llama` 는 들어왔다(정적 `resources/` 를 통해).

위 결정이 잘못된 게 아니라 **적용 지점이 틀렸다.** 자산 복사 스크립트가 두 개다:

| 스크립트 | 무엇을 복사하나 | 누가 부르나 |
| ------------------------------------------------- | --------------------------------- | ------------------------------------------------------- |
| `scripts/electron-build-resources.ts` (수정된 것) | 정적 자산 **+ 서브프로세스 서버** | `electron:build` 체인 (package.json:70) |
| `apps/electron/scripts/copy-assets.ts` | 정적 자산 + sapstack 에셋만 | **`build-win.ps1:396`** — 설치파일을 만드는 유일한 경로 |

`build-win.ps1` 은 `bun run electron:build` 를 통째로 부르지 않고 조각(esbuild main,
`electron:build:preload`, `vite build`, `copy-assets.ts`)을 직접 부른다. 그래서 수정된
스크립트가 **Windows 설치파일 경로에서 한 번도 실행되지 않았다.** `copy-assets.ts` 396행
주석의 "Single source of truth" 는 사실이 아니다.

### 왜 아직 안 고쳤나

`build-win.ps1` 에 `server:build:subprocess` + `electron:build:resources` 를 추가하려
했으나, **`pi-agent-server` 가 로컬에서 빌드되지 않는다**:

```
error: Could not resolve: "@aws-crypto/crc32"
at node_modules/.bun/@earendil-works+pi-ai@0.80.6+.../
@smithy/node-http-handler/node_modules/@smithy/core/dist-cjs/submodules/event-streams/index.js:1
```

- `@smithy/core@3.25.1` 이 `@aws-crypto/crc32: 5.2.0` 을 정식 dependency 로 선언한다
- `apps/desktop/bun.lock` 에도 등재돼 있고 `apps/desktop/node_modules/@aws-crypto/crc32` 는 존재한다
- 그런데 `apps/desktop/node_modules/@earendil-works/pi-ai` 는 **저장소 루트** 스토어
(`sapstack/node_modules/.bun/`) 로 심링크돼 있고, 그 스토어에는 crc32 가 없다
- `bun install --frozen-lockfile` 재실행으로도 복구되지 않았다

**추적 결과 — 루트 `node_modules` 를 두 패키지 매니저가 나눠 쓰고 있다.**

- 루트 `package.json` 의 workspaces 는 `["packages/*", "mcp", "extension"]` 로,
**`apps/desktop` 을 포함하지 않는다**. `apps/desktop` 은 자기 `bun.lock` 과 자기
workspaces 를 가진 독립 루트다
- 그런데 `apps/desktop` 에서 `bun install` 을 돌리면 bun 이 위로 올라가
루트 `package.json` 의 workspaces 필드를 보고 **`sapstack/` 을 모노레포 루트로 오인**해
스토어를 거기에 만든다
- 같은 `sapstack/node_modules` 를 ci.yml 이 `npm ci` (packages/runtime · mcp · extension)
로 따로 관리한다. npm 의 prune 이 bun 이 놓은 것을 걷어내면서 서브트리가 잘린다
- 실증: 해석 경로에 `@aws-crypto/crc32` 를 수동 배치하니 다음 결핍(`@aws-crypto/util`),
그 다음(`tslib`)이 연쇄로 드러났다 — 버전 충돌이 아니라 **서브트리 전체 부재**다
(확인 후 `node_modules` 는 원상 복구했다)

검증되지 않은 빌드 단계를 릴리스 워크플로에 넣으면 방금 복구한 파이프라인이 다시 깨진다.
**클린 체크아웃에서 `bun install` 후 `bun run server:build:subprocess` 가 통과하는지
먼저 확인**한 다음 `build-win.ps1` 을 고칠 것.

CI 러너는 매번 클린 체크아웃이라 통과할 가능성이 높지만(같은 `sapstack/node_modules` 를
npm 과 bun 이 순서대로 쓰기 때문에 CI 에서도 재현될 여지가 있다), 추측으로 워크플로를
바꾸지 않는다. 개발 머신에서 확인하지 못한 이유는 디스크 여유가 8.2G 뿐이라
클린 클론을 만들 수 없었기 때문이다.

> 근본 수리라면 `apps/desktop` 이 루트를 모노레포 루트로 오인하지 않게 만드는 것이다
> (루트 workspaces 에 명시적으로 넣거나, `apps/desktop` 에 경계를 세우거나).
> 이 결정 레코드의 범위를 넘으므로 별도 판단이 필요하다.

### 사용자 영향 (현재)

설치본 2.4.1 에서도 **로컬 모델 채팅은 여전히 `piServerPath not configured` 로 죽는다.**
v2.4.1 이 실제로 고친 것은 릴리스 파이프라인과 자동 업데이트 경로이지 이 결함이 아니다.
Loading