@kaydash9999/banker-plugins 0.25.0 → 0.25.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code skills + commands — QA, audit, docs, architecture, dependency setup, and wiki; the banker plugin marketplace.",
-    "version": "0.25.0"
+    "version": "0.25.1"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "banker",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Claude Code plugin: QA/audit/docs/architecture skills + commands, a /banker:setup installer for OS dependencies (playwright, etc.), and wiki compaction.",
   "author": {
     "name": "smallOpenSource",

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.25.1] - 2026-11-03
+
+### Fixed
+- `motion-sites`: Python 을 찾지 못해 첫 실행 구성이 멈출 때, 실패 이유와 `SKILL.md` 가 `MOTION_SITES_PYTHON` 으로 Python 을 지정하는 방법을 알린다. 전에는 PATH 밖의 Python(Windows 의 Miniconda, `py` 없이 Store 연결 파일만 있는 PC)을 쓸 방법이 안내되지 않았다. Windows 박스 실제 설치 시험에서 찾음.
+- `motion-sites`: `MOTION_SITES_PYTHON` 으로 지정한 Python 이 실행되지 않으면 그 사실을 알리고 멈춘다. 전에는 PATH 의 다른 Python 이 있으면 알리지 않고 그쪽에 Playwright 를 설치했다. 지정한 Python 으로 만든 캐시 폴더 가상 환경은 그대로 찾는다.
+- `3d-intro-build`, `3d-intro-setup`: 셸의 `FFMPEG_PATH` 가 상대 경로이거나 없는 파일이면 `resolveFfmpeg()` 가 그 까닭으로 멈춘다. 전에는 알리지 않고 설정 파일, PATH, `ffmpeg-static` 의 다른 ffmpeg 를 썼다. 설정 파일의 값은 예전처럼 쓸 수 없으면 다음 후보로 넘어간다.
+- `remains`: 박스 시험 실행기(`boxes.mjs`)가 저장소의 index 를 쓰지 않는다. `--ref worktree` 의 `git stash create` 는 index 사본으로, `git status` 는 선택 잠금 없이 돈다. 두 실행을 동시에 하거나 사용자의 git 명령이 index 를 잠그고 있으면 "could not write index" 로 멈추던 것을 고친다. 실패 문구가 `git -c -c stash create` 처럼 깨져 보이던 것도 고친다.
+- `remains`: root 로 접속해 `runAs` 계정으로 돌리는 Linux 박스는 개인 폴더를 `/tmp` 대신 `/var/lib` 아래에 만든다. 저장소 사본과 그 계정의 HOME 이 임시 폴더 아래에 있어, 임시 폴더를 거부하는 teamwork 의 설치 흐름 시험을 확인할 수 없던 것을 고친다.
+- 오류 주입 시험으로 찾은 "실패를 성공으로 보고" 를 고친다(omc-patch, ralph-qa 의 seat-run, verifier-probe, 3d-intro 의 azure-adapter, video-pool).
+  - `omc-patch`: 풀다 멈춘 판 폴더로 전환하던 것(옆 폴더에 다 푼 뒤에만 판 이름으로 옮기고, hooks.json 이나 scripts/ 가 없는 폴더는 설치된 판으로 보지 않음), hooks.json 이 없거나 훅을 하나도 부르지 않거나 부르는 훅 파일이 없을 때 "실패 0건" 이던 것, 빈 백업이나 잘린 백업으로 되돌리고 "되돌리기 완료" 이던 것, 깨진 hooks.json 을 "이 도구가 지운 적 없음" 으로 넘기던 것, 잘린 패치 파일과 패치 뒤 새로 생긴 감싸지 않은 import 를 `--check` 가 "모두 적용" 으로 보던 것, 오류 문구가 있는 git 종료 1 을 "origin 없음" 으로 보던 것
+  - `verifier-probe`: 두 호출이 모두 실패한 codex 를 앉힐 수 있는 좌석으로 보고하던 것(이제 `cli-call-failed` 와 호출이 끝난 사정), 읽지 못한 설정 파일(권한, 폴더)을 없는 파일로 보고 모델을 채택하던 것, 빈 models.dev 사본(`{}`)으로 채택하던 것, SIGTERM 을 무시하는 CLI 에 끝없이 멈추던 것(SIGKILL), 오류 글을 판으로 적던 것
+  - `seat-run`: 코드펜스 안의 `VERDICT:` 줄을 좌석의 판정으로 세던 것, 실패한 좌석의 `facts` 에 판정이 남던 것. send 출력에 `answered`, `failed` 를 더한다
+  - `3d-intro`: ffmpeg 가 실패하거나 끝나지 않거나 아무것도 쓰지 않아도 앞서 있던 파일이나 반쯤 쓴 파일을 결과로 내던 것(이제 출력부터 지우고 종료 0 과 빈 파일 아님을 요구, 10분 시간 제한), 길이를 읽지 못하면 0초에서 겹치던 crossfade, 200 으로 온 HTML, JSON 오류 페이지를 영상으로 받던 것, 이미지가 아닌 답을 PNG 로 내던 것, 빈 시드 프레임으로 유료 작업을 보내던 것
+
+### Notes
+- teamwork 시험은 저장소 사본이 임시 폴더 아래에 있으면(remains 박스 실행기 등) 설치 흐름 고정물을 홈 아래 난수 폴더에 두고 끝나면 지운다. 홈도 임시 폴더 아래면 설치 흐름 시험만 까닭을 대고 건너뛴다. 전에는 macOS, Rocky8 박스에서 74, 75건이 거짓 실패했다.
+- `scripts/class-guards.test.mjs` 는 git 저장소가 아닌 사본(박스에 보내는 추적 파일 묶음)에서도 파일을 걸어 돈다.
+
 ## [0.25.0] - 2026-11-02
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaydash9999/banker-plugins",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "banker — Claude Code + Codex CLI plugin (QA, audit, docs, architecture, wiki skills). Install via Claude Code marketplace, or `npm i -g @kaydash9999/banker-plugins` then `banker setup`.",
   "bin": {
     "banker": "bin/banker.js"

package/skills/3d-intro-build/SKILL.md

@@ -63,6 +63,7 @@ if (creds._tracked) throw new Error(`프로젝트 키 파일을 git 이 추적
 - `creds._ignored` 가 있으면 프로젝트 키 파일의 `FFMPEG_PATH` 를 쓰지 않은 것이다. 저장소와 함께 온 파일이 실행할 프로그램을 정하지 못하게 막은 것이다. 값은 출력하지 않으니 사람이 파일을 열어 확인하고, 그 경로가 필요하면 `3d-intro-setup` §2 로 홈 설정 파일에 남긴다.
   Claude Code: `/banker:setup` 에서 3d-intro-setup / Codex: `banker-3d-intro-setup`.
 - `resolveFfmpeg()` 가 throw 하면 ffmpeg 가 없다. 같은 `3d-intro-setup` 으로 보낸다.
+  - 오류가 `FFMPEG_PATH from the shell is not usable` 이면 셸에서 지정한 `FFMPEG_PATH` 가 상대 경로이거나 없는 파일이다. 다른 ffmpeg 로 넘어가지 않는다. 그 값을 고치거나 지우게 한다.
 - 둘 다 통과해야 다음 단계로 간다.
 - 영상 provider 상태를 무료로 확인해 둔다.
   `poolSummary({ creds })` 는 WAN 키별 상태(`ok`, `cooldown`, `exhausted`, `invalid`, `malformed`)와 마지막 줄의 Sora 상태(`label: 'AZURE_SORA'`, `ok`, `retired`, `unset`, `malformed`)를 키 원문 없이 돌려준다. WAN 줄은 `provider: 'wan'`, Sora 줄은 `provider: 'sora'` 다.

package/skills/3d-intro-build/references/azure-adapter.mjs

@@ -642,12 +642,26 @@ export async function generateImage({
 const classicWorthTrying = (r) => !(r.ok && dataB64(r)) && r.status !== 429 && r.status !== 0;
 const dataB64 = (r) => r.body?.data?.[0]?.b64_json;
 
-// The PNG an image call answered with, or an error that starts with `failed`.
+// The PNG an image call answered with, or an error that starts with `failed`. Bytes that are not an image (a URL or an
+// error text in the image field, base64 that decodes to nothing) are a failure, not a picture.
 function pngFrom(r, b64, failed) {
   if (!(r.ok && b64)) throw new Error(`${failed}: HTTP ${r.status}${why(r)} ${truncate(r.body)}`);
-  return Buffer.from(b64, 'base64');
+  const buf = Buffer.from(String(b64), 'base64');
+  if (!isImage(buf)) throw new Error(`${failed}: the answer is not a PNG, JPEG or WebP image (${buf.length} bytes)`);
+  return buf;
 }
 
+/** Whether bytes start as a PNG, JPEG or WebP image. */
+export const isImage = (b) => Buffer.isBuffer(b) && b.length >= 12 && (b.readUInt32BE(0) === 0x89504e47
+  || (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) || (b.toString('latin1', 0, 4) === 'RIFF' && b.toString('latin1', 8, 12) === 'WEBP'));
+
+/**
+ * Whether bytes start as an ISO media file (mp4, mov): the first box is one such a file starts with (ftyp, or styp,
+ * free, skip, wide, moov, mdat in fragmented and QuickTime files). An HTML or JSON error page is not.
+ */
+const MEDIA_BOXES = new Set(['ftyp', 'styp', 'free', 'skip', 'wide', 'moov', 'mdat']);
+export const isMp4 = (b) => Buffer.isBuffer(b) && b.length >= 12 && MEDIA_BOXES.has(b.toString('latin1', 4, 8));
+
 /** Edit an image (optional mask) via the v1 images/edits multipart path. Returns a PNG Buffer. */
 export async function editImage({
   endpoint, key, deployment, apiVersion = 'preview', prompt, imageBuf, maskBuf, size,
@@ -781,6 +795,7 @@ export async function downloadVideo({ endpoint, key, id, apiVersion = 'preview'
     key, method: 'GET', binary: true,
   });
   if (!(r.status === 200 && r.body?.length)) throw Object.assign(new Error(`downloadVideo failed: HTTP ${r.status}${why(r)}`), { status: r.status });
+  if (!isMp4(r.body)) throw Object.assign(new Error(`downloadVideo failed: HTTP 200 but the body is not an mp4 (${r.ct || 'no content type'}, ${r.body.length} bytes)`), { status: r.status });
   return r.body;
 }
 
@@ -919,7 +934,7 @@ function twoImageForm({ model, prompt, firstPng, lastPng, size, seconds }) {
  *   3) the optional ffmpeg-static package (dynamic import — may be absent)
  * A project's .env.3d-intro.local never names the program, and "." or another relative PATH entry is
  * skipped: either would let the files of a project, a cloned repository say, choose what runs.
- * Throws an actionable error if none is found.
+ * Throws an actionable error if none is found, or if $FFMPEG_PATH is set but not usable.
  */
 export async function resolveFfmpeg() {
   const found = namedFfmpeg() || ffmpegOnPath() || await staticFfmpeg();
@@ -928,10 +943,17 @@ export async function resolveFfmpeg() {
 }
 
 // The ffmpeg this machine names. Absolute only: a relative value would be looked up in the current
-// folder, the project. The files are read only when the shell names nothing usable.
+// folder, the project. A $FFMPEG_PATH from the shell is the user's choice for this run: when it is
+// relative or names no file, this stops with why instead of quietly taking another ffmpeg. The files
+// are read only when the shell names nothing.
 function namedFfmpeg() {
   const usable = (p) => !!p && path.isAbsolute(p) && fs.existsSync(p);
-  if (usable(process.env.FFMPEG_PATH)) return process.env.FFMPEG_PATH;
+  const shell = process.env.FFMPEG_PATH;
+  if (shell) {
+    if (usable(shell)) return shell;
+    const why = path.isAbsolute(shell) ? 'no such file' : 'not an absolute path';
+    throw new Error(`FFMPEG_PATH from the shell is not usable (${why}): ${shell}; fix it or unset it`);
+  }
   return [readSettings(), readEnvQuietly(homeCredsPath)].map((s) => s.FFMPEG_PATH).find(usable) || null;
 }
 
@@ -953,17 +975,30 @@ async function staticFfmpeg() {
 }
 
 // Run ffmpeg with an ARGUMENT ARRAY (never a shell string). Returns {code, stdout, stderr, args}.
+// ffmpeg has a time limit: a stuck one (a FIFO input, a blocked disk) would hold the whole run. SIGKILL, as a stuck
+// ffmpeg may not end on SIGTERM.
+export const FF_TIMEOUT_MS = 10 * 60 * 1000;
 function runFf(bin, args, cwd) {
-  const r = cp.spawnSync(bin, args, { cwd, encoding: 'utf8', maxBuffer: 1 << 28 });
-  return { code: r.status, stdout: r.stdout || '', stderr: r.stderr || '', args };
+  const r = cp.spawnSync(bin, args, { cwd, encoding: 'utf8', maxBuffer: 1 << 28, timeout: FF_TIMEOUT_MS, killSignal: 'SIGKILL' });
+  return { code: r.status, signal: r.signal || null, error: r.error || null, stdout: r.stdout || '', stderr: r.stderr || '', args };
+}
+
+// One ffmpeg run that must make `out`: an earlier file there is removed first, and the run counts only when ffmpeg
+// ended by itself with 0 and `out` is a file with something in it. A killed or failed ffmpeg's partial file is not a result.
+function ffOut(name, bin, args, out) {
+  fs.rmSync(out, { force: true });
+  const r = runFf(bin, args);
+  const size = (() => { try { return fs.statSync(out).size; } catch { return 0; } })();
+  if (r.code === 0 && size > 0) return out;
+  const how = r.error ? (r.error.code === 'ETIMEDOUT' ? `timed out after ${FF_TIMEOUT_MS / 1000} s` : r.error.code || r.error.message)
+    : r.signal ? `killed by ${r.signal}` : r.code !== 0 ? `exit ${r.code}: ${tail(r.stderr)}` : 'ffmpeg wrote no output';
+  throw new Error(`${name} failed: ${how}`);
 }
 
 /** Extract the exact LAST frame of an mp4 to a PNG (reverse + first-frame trick). Returns out. */
 export async function extractLastFrame(mp4, out, { ffmpeg } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
-  const r = runFf(bin, ['-y', '-i', mp4, '-vf', 'reverse', '-frames:v', '1', out]);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`extractLastFrame failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('extractLastFrame', bin, ['-y', '-i', mp4, '-vf', 'reverse', '-frames:v', '1', out], out);
 }
 
 /**
@@ -974,20 +1009,15 @@ export async function extractLastFrame(mp4, out, { ffmpeg } = {}) {
  */
 export async function stillToClip(png, out, { ffmpeg, seconds = 1, fps = 24, size } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
-  fs.rmSync(out, { force: true }); // a file from an earlier run must not pass for this one
   const vf = `${size ? `scale=${String(size).replace('x', ':')},` : ''}format=yuv420p`;
-  const r = runFf(bin, ['-y', '-loop', '1', '-i', png, '-t', String(seconds), '-r', String(fps), '-vf', vf,
-    '-c:v', 'libx264', '-crf', '20', '-g', '8', '-movflags', '+faststart', '-an', out]);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`stillToClip failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('stillToClip', bin, ['-y', '-loop', '1', '-i', png, '-t', String(seconds), '-r', String(fps), '-vf', vf,
+    '-c:v', 'libx264', '-crf', '20', '-g', '8', '-movflags', '+faststart', '-an', out], out);
 }
 
 /** Extract the FIRST frame of an mp4 to a PNG. Returns out. */
 export async function extractFirstFrame(mp4, out, { ffmpeg } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
-  const r = runFf(bin, ['-y', '-i', mp4, '-frames:v', '1', out]);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`extractFirstFrame failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('extractFirstFrame', bin, ['-y', '-i', mp4, '-frames:v', '1', out], out);
 }
 
 /**
@@ -1000,13 +1030,12 @@ export async function crossfade(aMp4, bMp4, out, sec = 0.5, { ffmpeg, offset } =
   let off = offset;
   if (off == null) {
     const dur = probeDurationSec(bin, aMp4);
-    off = dur != null ? Math.max(0, dur - sec) : 0;
+    // with A's length unknown, an offset of 0 would cut A to the fade: a wrong clip, not a result
+    if (dur == null) throw new Error(`crossfade failed: could not read the duration of ${path.basename(aMp4)}; pass { offset }`);
+    off = Math.max(0, dur - sec);
   }
   const filter = `[0:v][1:v]xfade=transition=fade:duration=${sec}:offset=${off}`;
-  const args = ['-y', '-i', aMp4, '-i', bMp4, '-filter_complex', filter, '-c:v', 'libx264', '-pix_fmt', 'yuv420p', out];
-  const r = runFf(bin, args);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`crossfade failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('crossfade', bin, ['-y', '-i', aMp4, '-i', bMp4, '-filter_complex', filter, '-c:v', 'libx264', '-pix_fmt', 'yuv420p', out], out);
 }
 
 /**
@@ -1015,9 +1044,7 @@ export async function crossfade(aMp4, bMp4, out, sec = 0.5, { ffmpeg, offset } =
  */
 export async function concatClips(mp4List, out, { ffmpeg, fps = 30, width = 720, height = 1280 } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
-  const r = runFf(bin, concatArgs(clipList(mp4List), out, { fps, width, height }));
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`concatClips failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('concatClips', bin, concatArgs(clipList(mp4List), out, { fps, width, height }), out);
 }
 
 function clipList(mp4List) {
@@ -1038,7 +1065,7 @@ function concatArgs(list, out, { fps, width, height }) {
 
 // Probe an mp4's duration (seconds) by parsing ffmpeg's stderr banner. Returns null if absent.
 function probeDurationSec(bin, mp4) {
-  const r = cp.spawnSync(bin, ['-i', mp4], { encoding: 'utf8' });
+  const r = cp.spawnSync(bin, ['-i', mp4], { encoding: 'utf8', timeout: FF_TIMEOUT_MS, killSignal: 'SIGKILL' });
   const text = `${r.stderr || ''}${r.stdout || ''}`;
   const m = text.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/);
   if (!m) return null;

package/skills/3d-intro-build/references/video-pool.mjs

@@ -43,7 +43,7 @@ import crypto from 'node:crypto';
 import cp from 'node:child_process';
 import {
   createVideo, pollVideo, downloadVideo, resolveFfmpeg, redact, fetchGuarded, safeForKey, keyHeldBack, probeSoraDeployment,
-  API_TIMEOUT_MS, DOWNLOAD_TIMEOUT_MS, HELD_KEY, errnoOf, timeLeft,
+  API_TIMEOUT_MS, DOWNLOAD_TIMEOUT_MS, HELD_KEY, errnoOf, timeLeft, isMp4, isImage, FF_TIMEOUT_MS,
 } from './azure-adapter.mjs';
 
 export const WAN_DEFAULT_MODEL = 'wan3.0-video-prime';
@@ -399,9 +399,11 @@ async function stripAlpha(buf) {
     const src = path.join(dir, 'in.png');
     const out = path.join(dir, 'out.png');
     fs.writeFileSync(src, buf);
-    const r = cp.spawnSync(bin, ['-y', '-i', src, '-vf', 'format=rgb24', '-frames:v', '1', out], { encoding: 'utf8' });
-    if (!fs.existsSync(out)) throw new Error(`stripAlpha failed: ${String(r.stderr || '').slice(-400)}`);
-    return fs.readFileSync(out);
+    const r = cp.spawnSync(bin, ['-y', '-i', src, '-vf', 'format=rgb24', '-frames:v', '1', out], { encoding: 'utf8', timeout: FF_TIMEOUT_MS, killSignal: 'SIGKILL' });
+    // only a run that ended by itself with 0: a killed ffmpeg's partial PNG would go to WAN as the frame
+    const png = r.status === 0 && fs.existsSync(out) ? fs.readFileSync(out) : null;
+    if (!png || !isImage(png)) throw new Error(`stripAlpha failed: ${r.error ? r.error.code : r.signal ? `killed by ${r.signal}` : String(r.stderr || '').slice(-400)}`);
+    return png;
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -410,6 +412,8 @@ async function stripAlpha(buf) {
 /** Encode a PNG/JPEG frame as the data URI WAN accepts, dropping any PNG alpha channel first. */
 export async function frameDataUri(buf) {
   const b = Buffer.isBuffer(buf) ? buf : fs.readFileSync(buf);
+  // an empty or non-image seed would be sent with a paid task and answered with a clip that does not start from it
+  if (!isImage(b)) throw new Error(`frameDataUri: the frame is not a PNG, JPEG or WebP image (${b.length} bytes)`);
   if (b[0] === 0xff && b[1] === 0xd8) return `data:image/jpeg;base64,${b.toString('base64')}`;
   const png = pngHasAlpha(b) ? await stripAlpha(b) : b;
   return `data:image/png;base64,${png.toString('base64')}`;
@@ -514,10 +518,11 @@ export async function downloadWanVideo(url, { sleep = realSleep, tries = 3 } = {
   let last;
   for (let i = 0; i < tries; i++) {
     last = await wanFetch(url, { binary: true, timeoutMs: DOWNLOAD_TIMEOUT_MS });
-    if (last.status === 200 && last.body?.length) return last.body;
+    // a 200 that is an HTML or JSON page (an expired or refused signed URL) is not the video: try again, then fail
+    if (last.status === 200 && isMp4(last.body)) return last.body;
     if (i < tries - 1) await sleep(2000 * (i + 1));
   }
-  throw new Error(`WAN video download failed: HTTP ${last?.status}`);
+  throw new Error(`WAN video download failed: HTTP ${last?.status}${last?.status === 200 ? ` but the body is not an mp4 (${last.body?.length ?? 0} bytes)` : ''}`);
 }
 
 /**

package/skills/3d-intro-setup/references/azure-adapter.mjs

@@ -642,12 +642,26 @@ export async function generateImage({
 const classicWorthTrying = (r) => !(r.ok && dataB64(r)) && r.status !== 429 && r.status !== 0;
 const dataB64 = (r) => r.body?.data?.[0]?.b64_json;
 
-// The PNG an image call answered with, or an error that starts with `failed`.
+// The PNG an image call answered with, or an error that starts with `failed`. Bytes that are not an image (a URL or an
+// error text in the image field, base64 that decodes to nothing) are a failure, not a picture.
 function pngFrom(r, b64, failed) {
   if (!(r.ok && b64)) throw new Error(`${failed}: HTTP ${r.status}${why(r)} ${truncate(r.body)}`);
-  return Buffer.from(b64, 'base64');
+  const buf = Buffer.from(String(b64), 'base64');
+  if (!isImage(buf)) throw new Error(`${failed}: the answer is not a PNG, JPEG or WebP image (${buf.length} bytes)`);
+  return buf;
 }
 
+/** Whether bytes start as a PNG, JPEG or WebP image. */
+export const isImage = (b) => Buffer.isBuffer(b) && b.length >= 12 && (b.readUInt32BE(0) === 0x89504e47
+  || (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) || (b.toString('latin1', 0, 4) === 'RIFF' && b.toString('latin1', 8, 12) === 'WEBP'));
+
+/**
+ * Whether bytes start as an ISO media file (mp4, mov): the first box is one such a file starts with (ftyp, or styp,
+ * free, skip, wide, moov, mdat in fragmented and QuickTime files). An HTML or JSON error page is not.
+ */
+const MEDIA_BOXES = new Set(['ftyp', 'styp', 'free', 'skip', 'wide', 'moov', 'mdat']);
+export const isMp4 = (b) => Buffer.isBuffer(b) && b.length >= 12 && MEDIA_BOXES.has(b.toString('latin1', 4, 8));
+
 /** Edit an image (optional mask) via the v1 images/edits multipart path. Returns a PNG Buffer. */
 export async function editImage({
   endpoint, key, deployment, apiVersion = 'preview', prompt, imageBuf, maskBuf, size,
@@ -781,6 +795,7 @@ export async function downloadVideo({ endpoint, key, id, apiVersion = 'preview'
     key, method: 'GET', binary: true,
   });
   if (!(r.status === 200 && r.body?.length)) throw Object.assign(new Error(`downloadVideo failed: HTTP ${r.status}${why(r)}`), { status: r.status });
+  if (!isMp4(r.body)) throw Object.assign(new Error(`downloadVideo failed: HTTP 200 but the body is not an mp4 (${r.ct || 'no content type'}, ${r.body.length} bytes)`), { status: r.status });
   return r.body;
 }
 
@@ -919,7 +934,7 @@ function twoImageForm({ model, prompt, firstPng, lastPng, size, seconds }) {
  *   3) the optional ffmpeg-static package (dynamic import — may be absent)
  * A project's .env.3d-intro.local never names the program, and "." or another relative PATH entry is
  * skipped: either would let the files of a project, a cloned repository say, choose what runs.
- * Throws an actionable error if none is found.
+ * Throws an actionable error if none is found, or if $FFMPEG_PATH is set but not usable.
  */
 export async function resolveFfmpeg() {
   const found = namedFfmpeg() || ffmpegOnPath() || await staticFfmpeg();
@@ -928,10 +943,17 @@ export async function resolveFfmpeg() {
 }
 
 // The ffmpeg this machine names. Absolute only: a relative value would be looked up in the current
-// folder, the project. The files are read only when the shell names nothing usable.
+// folder, the project. A $FFMPEG_PATH from the shell is the user's choice for this run: when it is
+// relative or names no file, this stops with why instead of quietly taking another ffmpeg. The files
+// are read only when the shell names nothing.
 function namedFfmpeg() {
   const usable = (p) => !!p && path.isAbsolute(p) && fs.existsSync(p);
-  if (usable(process.env.FFMPEG_PATH)) return process.env.FFMPEG_PATH;
+  const shell = process.env.FFMPEG_PATH;
+  if (shell) {
+    if (usable(shell)) return shell;
+    const why = path.isAbsolute(shell) ? 'no such file' : 'not an absolute path';
+    throw new Error(`FFMPEG_PATH from the shell is not usable (${why}): ${shell}; fix it or unset it`);
+  }
   return [readSettings(), readEnvQuietly(homeCredsPath)].map((s) => s.FFMPEG_PATH).find(usable) || null;
 }
 
@@ -953,17 +975,30 @@ async function staticFfmpeg() {
 }
 
 // Run ffmpeg with an ARGUMENT ARRAY (never a shell string). Returns {code, stdout, stderr, args}.
+// ffmpeg has a time limit: a stuck one (a FIFO input, a blocked disk) would hold the whole run. SIGKILL, as a stuck
+// ffmpeg may not end on SIGTERM.
+export const FF_TIMEOUT_MS = 10 * 60 * 1000;
 function runFf(bin, args, cwd) {
-  const r = cp.spawnSync(bin, args, { cwd, encoding: 'utf8', maxBuffer: 1 << 28 });
-  return { code: r.status, stdout: r.stdout || '', stderr: r.stderr || '', args };
+  const r = cp.spawnSync(bin, args, { cwd, encoding: 'utf8', maxBuffer: 1 << 28, timeout: FF_TIMEOUT_MS, killSignal: 'SIGKILL' });
+  return { code: r.status, signal: r.signal || null, error: r.error || null, stdout: r.stdout || '', stderr: r.stderr || '', args };
+}
+
+// One ffmpeg run that must make `out`: an earlier file there is removed first, and the run counts only when ffmpeg
+// ended by itself with 0 and `out` is a file with something in it. A killed or failed ffmpeg's partial file is not a result.
+function ffOut(name, bin, args, out) {
+  fs.rmSync(out, { force: true });
+  const r = runFf(bin, args);
+  const size = (() => { try { return fs.statSync(out).size; } catch { return 0; } })();
+  if (r.code === 0 && size > 0) return out;
+  const how = r.error ? (r.error.code === 'ETIMEDOUT' ? `timed out after ${FF_TIMEOUT_MS / 1000} s` : r.error.code || r.error.message)
+    : r.signal ? `killed by ${r.signal}` : r.code !== 0 ? `exit ${r.code}: ${tail(r.stderr)}` : 'ffmpeg wrote no output';
+  throw new Error(`${name} failed: ${how}`);
 }
 
 /** Extract the exact LAST frame of an mp4 to a PNG (reverse + first-frame trick). Returns out. */
 export async function extractLastFrame(mp4, out, { ffmpeg } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
-  const r = runFf(bin, ['-y', '-i', mp4, '-vf', 'reverse', '-frames:v', '1', out]);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`extractLastFrame failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('extractLastFrame', bin, ['-y', '-i', mp4, '-vf', 'reverse', '-frames:v', '1', out], out);
 }
 
 /**
@@ -974,20 +1009,15 @@ export async function extractLastFrame(mp4, out, { ffmpeg } = {}) {
  */
 export async function stillToClip(png, out, { ffmpeg, seconds = 1, fps = 24, size } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
-  fs.rmSync(out, { force: true }); // a file from an earlier run must not pass for this one
   const vf = `${size ? `scale=${String(size).replace('x', ':')},` : ''}format=yuv420p`;
-  const r = runFf(bin, ['-y', '-loop', '1', '-i', png, '-t', String(seconds), '-r', String(fps), '-vf', vf,
-    '-c:v', 'libx264', '-crf', '20', '-g', '8', '-movflags', '+faststart', '-an', out]);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`stillToClip failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('stillToClip', bin, ['-y', '-loop', '1', '-i', png, '-t', String(seconds), '-r', String(fps), '-vf', vf,
+    '-c:v', 'libx264', '-crf', '20', '-g', '8', '-movflags', '+faststart', '-an', out], out);
 }
 
 /** Extract the FIRST frame of an mp4 to a PNG. Returns out. */
 export async function extractFirstFrame(mp4, out, { ffmpeg } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
-  const r = runFf(bin, ['-y', '-i', mp4, '-frames:v', '1', out]);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`extractFirstFrame failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('extractFirstFrame', bin, ['-y', '-i', mp4, '-frames:v', '1', out], out);
 }
 
 /**
@@ -1000,13 +1030,12 @@ export async function crossfade(aMp4, bMp4, out, sec = 0.5, { ffmpeg, offset } =
   let off = offset;
   if (off == null) {
     const dur = probeDurationSec(bin, aMp4);
-    off = dur != null ? Math.max(0, dur - sec) : 0;
+    // with A's length unknown, an offset of 0 would cut A to the fade: a wrong clip, not a result
+    if (dur == null) throw new Error(`crossfade failed: could not read the duration of ${path.basename(aMp4)}; pass { offset }`);
+    off = Math.max(0, dur - sec);
   }
   const filter = `[0:v][1:v]xfade=transition=fade:duration=${sec}:offset=${off}`;
-  const args = ['-y', '-i', aMp4, '-i', bMp4, '-filter_complex', filter, '-c:v', 'libx264', '-pix_fmt', 'yuv420p', out];
-  const r = runFf(bin, args);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`crossfade failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('crossfade', bin, ['-y', '-i', aMp4, '-i', bMp4, '-filter_complex', filter, '-c:v', 'libx264', '-pix_fmt', 'yuv420p', out], out);
 }
 
 /**
@@ -1015,9 +1044,7 @@ export async function crossfade(aMp4, bMp4, out, sec = 0.5, { ffmpeg, offset } =
  */
 export async function concatClips(mp4List, out, { ffmpeg, fps = 30, width = 720, height = 1280 } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
-  const r = runFf(bin, concatArgs(clipList(mp4List), out, { fps, width, height }));
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`concatClips failed: ${tail(r.stderr)}`);
-  return out;
+  return ffOut('concatClips', bin, concatArgs(clipList(mp4List), out, { fps, width, height }), out);
 }
 
 function clipList(mp4List) {
@@ -1038,7 +1065,7 @@ function concatArgs(list, out, { fps, width, height }) {
 
 // Probe an mp4's duration (seconds) by parsing ffmpeg's stderr banner. Returns null if absent.
 function probeDurationSec(bin, mp4) {
-  const r = cp.spawnSync(bin, ['-i', mp4], { encoding: 'utf8' });
+  const r = cp.spawnSync(bin, ['-i', mp4], { encoding: 'utf8', timeout: FF_TIMEOUT_MS, killSignal: 'SIGKILL' });
   const text = `${r.stderr || ''}${r.stdout || ''}`;
   const m = text.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/);
   if (!m) return null;

package/skills/3d-intro-setup/references/video-pool.mjs

@@ -43,7 +43,7 @@ import crypto from 'node:crypto';
 import cp from 'node:child_process';
 import {
   createVideo, pollVideo, downloadVideo, resolveFfmpeg, redact, fetchGuarded, safeForKey, keyHeldBack, probeSoraDeployment,
-  API_TIMEOUT_MS, DOWNLOAD_TIMEOUT_MS, HELD_KEY, errnoOf, timeLeft,
+  API_TIMEOUT_MS, DOWNLOAD_TIMEOUT_MS, HELD_KEY, errnoOf, timeLeft, isMp4, isImage, FF_TIMEOUT_MS,
 } from './azure-adapter.mjs';
 
 export const WAN_DEFAULT_MODEL = 'wan3.0-video-prime';
@@ -399,9 +399,11 @@ async function stripAlpha(buf) {
     const src = path.join(dir, 'in.png');
     const out = path.join(dir, 'out.png');
     fs.writeFileSync(src, buf);
-    const r = cp.spawnSync(bin, ['-y', '-i', src, '-vf', 'format=rgb24', '-frames:v', '1', out], { encoding: 'utf8' });
-    if (!fs.existsSync(out)) throw new Error(`stripAlpha failed: ${String(r.stderr || '').slice(-400)}`);
-    return fs.readFileSync(out);
+    const r = cp.spawnSync(bin, ['-y', '-i', src, '-vf', 'format=rgb24', '-frames:v', '1', out], { encoding: 'utf8', timeout: FF_TIMEOUT_MS, killSignal: 'SIGKILL' });
+    // only a run that ended by itself with 0: a killed ffmpeg's partial PNG would go to WAN as the frame
+    const png = r.status === 0 && fs.existsSync(out) ? fs.readFileSync(out) : null;
+    if (!png || !isImage(png)) throw new Error(`stripAlpha failed: ${r.error ? r.error.code : r.signal ? `killed by ${r.signal}` : String(r.stderr || '').slice(-400)}`);
+    return png;
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -410,6 +412,8 @@ async function stripAlpha(buf) {
 /** Encode a PNG/JPEG frame as the data URI WAN accepts, dropping any PNG alpha channel first. */
 export async function frameDataUri(buf) {
   const b = Buffer.isBuffer(buf) ? buf : fs.readFileSync(buf);
+  // an empty or non-image seed would be sent with a paid task and answered with a clip that does not start from it
+  if (!isImage(b)) throw new Error(`frameDataUri: the frame is not a PNG, JPEG or WebP image (${b.length} bytes)`);
   if (b[0] === 0xff && b[1] === 0xd8) return `data:image/jpeg;base64,${b.toString('base64')}`;
   const png = pngHasAlpha(b) ? await stripAlpha(b) : b;
   return `data:image/png;base64,${png.toString('base64')}`;
@@ -514,10 +518,11 @@ export async function downloadWanVideo(url, { sleep = realSleep, tries = 3 } = {
   let last;
   for (let i = 0; i < tries; i++) {
     last = await wanFetch(url, { binary: true, timeoutMs: DOWNLOAD_TIMEOUT_MS });
-    if (last.status === 200 && last.body?.length) return last.body;
+    // a 200 that is an HTML or JSON page (an expired or refused signed URL) is not the video: try again, then fail
+    if (last.status === 200 && isMp4(last.body)) return last.body;
     if (i < tries - 1) await sleep(2000 * (i + 1));
   }
-  throw new Error(`WAN video download failed: HTTP ${last?.status}`);
+  throw new Error(`WAN video download failed: HTTP ${last?.status}${last?.status === 200 ? ` but the body is not an mp4 (${last.body?.length ?? 0} bytes)` : ''}`);
 }
 
 /**

package/skills/motion-sites/SKILL.md

@@ -29,7 +29,7 @@ banker 는 원본을 복사하지 않는다. 원본의 예시(`examples/`)와
 |---|---|
 | `skillFile` | 설치된 원본 `SKILL.md` 경로. 없거나 꺼져 있으면 `null` |
 | `disabled` | 설치는 됐지만 꺼져 있음 |
-| `python.bin` | Playwright 를 쓸 Python |
+| `python.bin` | Playwright 를 쓸 Python. 찾는 차례는 `MOTION_SITES_PYTHON`, 캐시 폴더의 가상 환경, PATH 의 `python3`, `python`(Windows 는 `py -3`, `python`). `MOTION_SITES_PYTHON` 이 있으면 그것과 캐시 폴더의 가상 환경만 보고, 지정한 것이 실행되지 않으면 다른 Python 으로 넘어가지 않는다 |
 | `python.playwright`, `python.chromium` | Playwright 와 Chromium 이 있는지 |
 | `ready` | 셋 다 있으면 `true`(종료 0) |
 
@@ -49,6 +49,14 @@ banker 는 원본을 복사하지 않는다. 원본의 예시(`examples/`)와
 3. Codex 에서는 이 명령이 네트워크와 `~/.codex` 쓰기를 하므로 `sandbox_permissions: "require_escalated"` 로 승인을 요청한다.
 4. 출력의 `steps` 에 실패한 단계가 있으면 그 단계와 `why` 를 보여 주고 멈춘다. 설치되지 않은 것을 설치된 것처럼 말하지 않는다.
    - 네트워크가 없으면 여기서 멈춘다. 오프라인에서는 이 스킬을 쓸 수 없다.
+   - `python` 단계가 "Python 3 을 찾지 못함" 으로 실패하면, 설치한 Python 이 PATH 밖에 있는지 사용자에게 묻는다. Windows 에서 `py` 가 없고 PATH 의 `python` 이 Microsoft Store 연결 파일뿐이거나, Miniconda 를 PATH 에 넣지 않고 설치한 경우다.
+   - 있으면 그 python 실행 파일의 절대 경로를 환경 변수 `MOTION_SITES_PYTHON` 에 영구로 지정하라고 안내한다. `%USERPROFILE%`, `~` 같은 줄임은 쓰지 않는다. 셸에 따라 글자 그대로 저장되어 엔진이 찾지 못한다.
+     - Windows(cmd 나 PowerShell): `setx MOTION_SITES_PYTHON "C:\Users\<이름>\miniconda3\python.exe"`
+     - macOS, Linux: 셸 설정 파일(`~/.zshrc`, `~/.bashrc`)에 `export MOTION_SITES_PYTHON=/절대/경로/python3`
+   - 한 번만 주는 것으로는 안 된다. 다음 실행의 상태 확인도 그 Python 을 봐야 한다. 이미 떠 있는 프로그램에는 새 값이 반영되지 않으므로, Claude Code 나 Codex 를 완전히 끝내고 다시 시작한 뒤 2단계를 다시 한다.
+   - Playwright 는 지정한 Python 에 설치된다. 그 Python 을 바꾸고 싶지 않으면 `<그 python> -m venv <폴더>` 로 가상 환경을 만들고 그 안의 python 을 지정한다(Windows `<폴더>\Scripts\python.exe`, macOS 와 Linux `<폴더>/bin/python`). pip 이 시스템 Python 을 거부하는(externally managed) 경우는 엔진이 캐시 폴더에 가상 환경을 스스로 만든다.
+   - 실패 이유가 "MOTION_SITES_PYTHON 에 지정한 ... 가 실행되지 않음" 이면 지정한 경로가 틀린 것이다. 경로를 고치게 한다.
+   - Python 이 없으면 Python 3 설치를 안내한다. 직접 설치하지 않는다.
    - Linux 에서 Chromium 이 시스템 라이브러리 부족으로 뜨지 않으면 `<python.bin> -m playwright install-deps chromium` 을 안내한다. 관리자 권한이 필요하므로 직접 실행하지 않는다.
 5. 끝나면 `ready` 가 `true` 인지 확인하고 3단계로 간다.
 

package/skills/motion-sites/scripts/motion-sites.mjs

@@ -215,9 +215,16 @@ export function lookPython(py, runner = run) {
   return { bin, cmd: py, playwright: pw, chromium: exe.ok && chrome !== "" && existsSync(chrome) };
 }
 
-/** The first Python with Playwright (and Chromium, when one has both), else the first that runs. */
+/**
+ * The first Python with Playwright (and Chromium, when one has both), else the first that runs. A MOTION_SITES_PYTHON
+ * is the user's choice: only it and the cache's virtual environment (made from it when pip refuses it) are looked at,
+ * and when it does not run there is none, so Playwright never goes into a Python the user did not name.
+ */
 export function pickPython(env = process.env, runner = run) {
-  const seen = pythons(env).map((p) => lookPython(p, runner)).filter(Boolean);
+  const all = pythons(env);
+  const named = env.MOTION_SITES_PYTHON ? lookPython(all[0], runner) : null;
+  if (env.MOTION_SITES_PYTHON && !named) return null;
+  const seen = (named ? [named, lookPython(all[1], runner)] : all.map((p) => lookPython(p, runner))).filter(Boolean);
   return seen.find((p) => p.playwright && p.chromium) ?? seen.find((p) => p.playwright) ?? seen[0] ?? null;
 }
 
@@ -265,10 +272,20 @@ function enablePlugin(runtime, runner) {
   return { step: "plugin enable", ok: r.ok, why: r.why };
 }
 
+// No Python found: says where it looked and how to name one that is installed but not on PATH (Windows with only
+// Miniconda, or only the Microsoft Store link, has no py and no working python).
+export const NO_PYTHON = "Python 3 을 찾지 못함(python3, python, Windows 는 py). 설치한 Python 이 PATH 밖에 있으면 환경 변수 MOTION_SITES_PYTHON 에 그 python 실행 파일의 절대 경로를 영구로 지정한 뒤 다시 실행";
+
+/** Why no Python was found; a MOTION_SITES_PYTHON that is set but does not run is named, so a typo is not hidden. */
+export function noPython(env = process.env) {
+  if (!env.MOTION_SITES_PYTHON) return NO_PYTHON;
+  return `MOTION_SITES_PYTHON 에 지정한 ${pythons(env)[0][0]} 가 실행되지 않음. 경로를 고친 뒤 다시 실행. ${NO_PYTHON}`;
+}
+
 /** The Python steps: Playwright, then Chromium. */
 function installBrowser(env, runner) {
   let py = pickPython(env, runner);
-  if (!py) return [{ step: "python", ok: false, why: "Python 3 을 찾지 못함(python3, python, Windows 는 py)" }];
+  if (!py) return [{ step: "python", ok: false, why: noPython(env) }];
   const steps = [];
   let cmd = py.cmd;
   if (!py.playwright) {

package/skills/omc-patch/scripts/omc-patch.mjs

@@ -252,8 +252,10 @@ function gitFetch(args) {
 // ── 1. 업데이트 ──────────────────────────────────────────────────────────────
 function ensureVersion() {
   const have = installedVersions();
-  if (have.includes(TARGET_VERSION)) return useCached();
-  if (MODE === "check") { bad(`${TARGET_VERSION} 미설치 (설치된 버전: ${have.join(", ") || "없음"})`); return false; }
+  if (have.includes(TARGET_VERSION) && completeVersion(TARGET_VERSION)) return useCached();
+  // 풀다 멈춘 폴더(hooks/hooks.json 이나 scripts/ 가 없음)는 설치된 것으로 보지 않는다. 그대로 전환하면 빈 플러그인으로 바뀐다.
+  if (have.includes(TARGET_VERSION)) bad(`${TARGET_VERSION} 캐시 폴더가 불완전함 (hooks/hooks.json 이나 scripts/ 가 없음)${MODE === "check" ? "" : ". 다시 풉니다"}`);
+  if (MODE === "check") { if (!have.includes(TARGET_VERSION)) bad(`${TARGET_VERSION} 미설치 (설치된 버전: ${have.join(", ") || "없음"})`); return false; }
   if (!canInstallTarget()) return false;
 
   log(`  ${TARGET_VERSION} 설치 중...`);
@@ -265,6 +267,9 @@ function ensureVersion() {
   return switchActive(sha);
 }
 
+// 판 폴더에 훅 목록과 스크립트 폴더가 있는가.
+const completeVersion = (v) => existsSync(join(CACHE, v, "hooks", "hooks.json")) && existsSync(join(CACHE, v, "scripts"));
+
 // TARGET_VERSION 이 캐시에 있을 때. 이미 활성이면 끝, 아니면 마켓플레이스 태그의 커밋으로 전환한다.
 // 전환도 마켓플레이스와 git 이 있어야 하므로 먼저 확인한다(풀지 않으므로 tar 는 없어도 된다).
 function useCached() {
@@ -356,16 +361,27 @@ function targetSha() {
 }
 
 // git archive | tar 로 소스를 편다. 저장소에 dist/ 가 포함되어 빌드는 불필요하다.
+// 옆의 난수 이름 폴더에 다 푼 뒤에만 판 이름으로 옮긴다. 도중에 멈추면(tar 실패, 신호, 디스크 부족) 판 이름의 폴더는 생기지 않아,
+// 다음 실행이 반쯤 찬 폴더를 설치된 판으로 보고 전환하지 않는다. 옆 폴더는 판 이름 꼴이 아니라 installedVersions 가 세지 않는다.
 function unpackTarget(dest) {
-  if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
-  mkdirSync(dest, { recursive: true });
-  git(["archive", `v${TARGET_VERSION}`, "-o", join(dest, "_src.tar")]);
-  execFileSync("tar", ["-xf", join(dest, "_src.tar"), "-C", dest], { cwd: homedir(), stdio: "ignore" });
-  unlinkSync(join(dest, "_src.tar"));
+  const part = `${dest}.part-${randomBytes(6).toString("hex")}`;
+  mkdirSync(part, { recursive: true });
+  try {
+    git(["archive", `v${TARGET_VERSION}`, "-o", join(part, "_src.tar")]);
+    execFileSync("tar", ["-xf", join(part, "_src.tar"), "-C", part], { cwd: homedir(), stdio: "ignore" });
+    unlinkSync(join(part, "_src.tar"));
+    if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
+    renameSync(part, dest);
+  } catch (e) {
+    rmSync(part, { recursive: true, force: true });
+    throw e;
+  }
 }
 
 // node_modules 는 복사하지 않고 직전 버전 것을 링크한다. Windows 는 junction
 // (관리자 권한 불필요), POSIX 는 type 인자가 무시되고 디렉터리 symlink 가 된다.
+// 없어도 전환을 막지 않는다. Claude Code 가 직접 설치한 OMC 판에는 node_modules 가 없고, 실행에 쓰는 것은 dist/ 에
+// 묶여 있다(2026-11-03 실측: 5.7.21~5.7.30 모두 없음, OMC 정상 동작). 막으면 보통 PC 에서 전환이 늘 실패한다.
 function linkNodeModules(dest, have) {
   const prev = have.find((v) => v !== TARGET_VERSION);
   const nm = join(dest, "node_modules");
@@ -699,16 +715,22 @@ function openParenOf(src, j) {
 // 그 상태를 «패치됨» 으로 넘기면 --check 가 결함 트리에 «모두 적용» 을 낸다(2026-10-12 실측).
 function siteInfo(src) {
   if (src.includes("__omcRaceImport")) {
-    const why = helperDefect(scanFacts(src));
+    // 헬퍼가 있어도 적용이 감쌌어야 할 자리가 남았으면(패치 뒤 상류가 줄을 더함) 적용된 것이 아니다.
+    // 헬퍼 본문의 Promise.race 는 손으로 두른 것이 아니므로, 같은 길이의 공백으로 지운 글에서 찾는다(자리는 그대로).
+    const left = openSites(src.split(HELPER).join(" ".repeat(HELPER.length)));
+    const why = helperDefect(scanFacts(src)) ?? (left.length ? `감싸지 않은 최상위 await import 가 남음 :${left.map((p) => src.slice(0, p).split("\n").length).join(", :")}` : null);
     return why ? { state: "misplaced", sites: [], why } : { state: "patched", sites: [] };
   }
   const all = scanTopLevelAwaitImports(src);
   if (!all.length) return { state: "n/a", sites: [] };
-  const open = all.filter((p) => !/Promise\.race/.test(src.slice(Math.max(0, p - 300), p)));
+  const open = openSites(src);
   if (!open.length) return { state: "guarded", sites: [] };
   return { state: "needs", sites: open };
 }
 
+// 적용이 감싸는 자리: 최상위 await import 가운데 바로 앞(300자)에 손으로 두른 Promise.race 가 없는 것.
+const openSites = (src) => scanTopLevelAwaitImports(src).filter((p) => !/Promise\.race/.test(src.slice(Math.max(0, p - 300), p)));
+
 // 헬퍼가 쓰일 수 없는 자리면 그 이유를, 제자리면 null 을 낸다.
 //   - 선언이 블록 안(깊이 1 이상): 다른 블록의 자리에서 ReferenceError(옛 킷이 남긴 자리)
 //   - 선언을 못 찾음: 이름만으로는 «패치됨» 이라 할 근거가 없다. 앞쪽 글을 토크나이저가 잘못
@@ -834,15 +856,33 @@ function patchHooks(root) {
   // 4.15.7 이 둘 다 겪었다 — PostToolUse 를 지우면 그 스크립트가 목록에서 빠지고(그래서
   // .omcbak 이 있어도 안 돌아온다), 손으로 고친 파일은 .omcbak 조차 없어 아예 안 보인다.
   const names = MODE === "revert" ? scriptNames(root, r) : hookNames(root);
+  // 고칠 훅을 하나도 찾지 못했으면 «실패 0건» 이 아니다. 목록이 빈 hooks.json(`{}`, `[]`)은 고친 것도 확인한 것도 없다.
+  // hooks.json 이 없거나 읽히지 않으면 [3/4] 가 이름과 이유를 대고 센다. 여기서는 읽혔는데 훅이 없을 때만 센다.
+  if (MODE !== "revert" && !names.length) {
+    if (readableFile(join(root, "hooks", "hooks.json"))) notChecked(r, join(root, "hooks", "hooks.json"), "hooks.json 이 부르는 훅(scripts/*.mjs)을 하나도 찾지 못함");
+    return r;
+  }
   for (const n of names) {
     const f = join(root, "scripts", `${n}.mjs`);
-    if (!existsSync(f)) continue;
-    if (MODE === "revert") revertScript(root, n, f, r);
-    else checkOrPatchScript(root, n, f, r);
+    if (MODE === "revert") { if (existsSync(f)) revertScript(root, n, f, r); continue; }
+    // hooks.json 이 부르는데 파일이 없으면 이름을 대고 센다. 그 밖에 볼 수 없으면(권한) readHook 이 이유를 대고 센다.
+    if (missingFile(f)) { notChecked(r, f, `hooks.json 이 부르는 훅 파일이 없음: ${shown(n)}`); continue; }
+    checkOrPatchScript(root, n, f, r);
   }
   return r;
 }
 
+// 확인하지 못한 것: 이름과 이유를 대고 실패로 센다. check 는 «모두 적용» 이라 하지 않게 읽지 못한 것으로도 센다.
+function notChecked(r, f, why) {
+  bad(why);
+  r.fail++;
+  r.failed.push(f);
+  if (MODE === "check") r.unread++;
+}
+
+const readableFile = (f) => { try { readRegular(f); return true; } catch { return false; } };
+const missingFile = (f) => { try { lstatSync(f); return false; } catch (e) { return e.code === "ENOENT"; } };
+
 // revert 가 훑는 이름: scripts/ 의 .mjs 전부. scripts/ 가 없는 판 폴더는 되돌릴 훅이 없어 한 줄로 알리고 넘어간다.
 // 그 밖에 목록을 읽지 못하면(파일, 권한) 이름과 이유를 대고 실패로 센다 — 다음 판과 [3/4], [4/4] 는 그대로 간다.
 function scriptNames(root, r) {
@@ -927,12 +967,20 @@ function handRestoreHint(bak, f) {
 
 // 백업의 내용으로 파일을 바꾼다. 쓰지 못하면 그 이유, 백업이 읽으려는 순간 사라졌으면 GONE, 아니면 null.
 const GONE = "백업이 먼저 사라짐";
+// 빈 백업이나 문법 검사를 통과하지 못하는 백업(잘린 복사)으로는 되돌리지 않는다. 쓴 뒤 검사에 걸리면 쓰기 전 글로 되돌린다.
 function restoreFrom(f, bak) {
   let data;
   try { data = readRegular(bak); }
   catch (e) { return e.code === "ENOENT" ? GONE : `읽지 못함: ${failWhy(e)}`; }
-  try { writeAtomic(f, data); return null; }
+  if (!data.length) return "백업이 비어 있음";
+  let before;
+  try { before = readRegular(f); writeAtomic(f, data); }
   catch (e) { return `쓰지 못함: ${failWhy(e)}`; }
+  const err = syntaxError(f);
+  if (!err) return null;
+  try { writeAtomic(f, before); }
+  catch (e) { return `백업이 문법 검사를 통과하지 못했고 원래 글로도 되돌리지 못함 (${failWhy(e)}): ${oneLine(err)}`; }
+  return `백업이 문법 검사를 통과하지 못함: ${oneLine(err)}`;
 }
 
 // 되돌린 뒤 백업을 지운다. 다른 실행이 먼저 지웠으면(ENOENT) 된 것이다. 못 지우면 그 이유, 아니면 null.
@@ -948,6 +996,9 @@ function checkOrPatchScript(root, n, f, r) {
   // 헬퍼 자리 결함은 check 와 apply 모두 이름을 댄다. 이미 감싼 파일이라 transform 으로는
   // 고칠 수 없으므로 apply 도 건드리지 않고, 되돌린 뒤 다시 적용하라고 안내한다(misplacedHint).
   if (info.state === "misplaced") { bad(`헬퍼 자리 결함: ${n} (${info.why})`); r.misplaced++; return; }
+  // 헬퍼 이름이 있어도 잘린 파일(복사가 끊김)은 돌지 않는다. 문법 검사를 통과해야 패치된 것으로 센다.
+  const broken = info.state === "patched" ? syntaxError(f) : null;
+  if (broken) { bad(`헬퍼 자리 결함: ${n} (패치된 파일이 문법 검사를 통과하지 못함: ${oneLine(broken)})`); r.misplaced++; return; }
   if (info.state !== "needs") { r.skip++; return; }
   const bak = `${f}.omcbak`;
   const why = whyNotWrite(root, f, bak);
@@ -1079,6 +1130,7 @@ function revertHooksJson(root, hj) {
   const bak = `${hj}.omcbak`;
   const saved = readBackup(bak);
   if (saved !== null) {
+    if (!isJson(saved)) { hjBad("hooks.json 을 되돌리지 않음 (백업이 비었거나 JSON 이 아님)"); return "unsafe"; }
     if (staleHooksJson(hj, saved)) { hjBad(`hooks.json 을 되돌리지 않음 (지금 파일에 PostToolUse 가 있고 백업과 글이 다름. 백업이 옛 원본일 수 있음)`); return "unsafe"; }
     writeAtomic(hj, saved);
     log(`  되돌림  ${hjTag}hooks.json`);
@@ -1102,9 +1154,14 @@ function revertHooksJson(root, hj) {
     return "reverted";
   }
   if (usable.length > 1) { hjBad(`hooks.json 수동 백업이 여러 개라 자동 복구하지 않음: ${usable.map(shown).join(", ")}`); return "ambiguous"; }
-  return unsafe.length ? "linked" : "no-backup";
+  if (unsafe.length) return "linked";
+  // 깨진 hooks.json 에 되돌릴 백업도 없으면 «이 도구가 지운 적 없음» 이라 할 근거가 없다. 그대로 두고 실패로 센다.
+  if (!isJson(readHooksJson(hj))) { hjBad("hooks.json 이 JSON 이 아니고 되돌릴 백업도 없음"); return "unsafe"; }
+  return "no-backup";
 }
 
+const isJson = (text) => { try { JSON.parse(String(text)); return true; } catch { return false; } };
+
 // 파일에서 읽은 값(파일 이름, PINNED 의 host)과 출력하는 경로를 출력에 넣을 때 쓴다. 줄바꿈과 제어 문자를 ? 로 바꾸고 길이를 자른다.
 // SKILL 은 [!] 줄을 그대로 보고하라고 하므로, 값이 제 줄을 새로 시작하면 도구가 낸 줄처럼 읽힌다.
 // 바꾸는 문자: 제어 문자(Cc), 서식 문자(Cf: 폭 없는 공백, 방향 표시, 단어 결합자, 태그 문자), 줄과 문단 구분자,
@@ -1270,7 +1327,7 @@ function removePostToolUse(hj, why) {
 // 고정과 되돌리기가 하지 않은 일을 했다고 끝난다.
 function originUrl() {
   try { return git(["config", "--get", "remote.origin.url"]); }
-  catch (e) { return e.status === 1 ? null : { unreadable: gitLine(e) }; }
+  catch (e) { return e.status === 1 && !String(e.stderr || "").trim() ? null : { unreadable: gitLine(e) }; }
 }
 
 // git 오류의 원인 줄: `fatal:` 이나 `error:` 로 시작하는 첫 줄, 없으면 첫 줄(`warning:` 이 먼저 올 수 있다), 정화하고
@@ -1688,7 +1745,8 @@ for (const v of targets) {
   else if (hj === "needs") hjNeedBy[v] = true;
   else if (hj === "reverted" || hj === "ambiguous" || hj === "linked") { /* patchHooksJson 이 출력함 */ }
   else if (hj === "no-backup") ok(`${tag}되돌릴 백업 없음 (이 도구가 지운 적 없음)`);
-  else if (hj === "no-file") bad(`${tag}hooks.json 파일 자체가 없음`);
+  // 판 폴더에 hooks.json 이 없으면 고친 것도 확인한 것도 없다. 실패로 센다.
+  else if (hj === "no-file") { bad(`${tag}hooks.json 파일 자체가 없음`); r.fail++; hjFailBy[v] = true; failed.add(fileKey(join(root, "hooks", "hooks.json"))); }
   // "failed" 는 고친 hooks.json 이 JSON 으로 읽히지 않아 되돌린 경우다. 고치지 못했으니 실패로 센다.
   else if (hj === "unsafe" || hj === "failed") { r.fail++; hjFailBy[v] = true; failed.add(fileKey(join(root, "hooks", "hooks.json"))); }
   if (hj === "ambiguous" || hj === "linked") left.add(fileKey(join(root, "hooks", "hooks.json")));

package/skills/ralph-qa/SKILL.md

@@ -408,6 +408,7 @@ node '<R>/gate-evidence.mjs' cleanup --dir '<g>'
 
 ### 3. 판정 수신
 각 좌석에서 4값 중 하나를 받는다. 외부 좌석은 **단독 줄 `VERDICT: <값>`** 이 필수이며, 부재·중복·절단·파싱실패·거부는 `ERROR` 다.
+코드펜스(```, ~~~) 안의 `VERDICT:` 줄은 인용한 글이라 세지 않는다. 판정 줄을 코드펜스로 감싼 답은 판정 줄이 없는 답이라 `ERROR` 다. send 출력의 `answered`, `failed` 는 답한 좌석과 실패한 좌석의 수다. `ok: true` 는 send 가 돌았다는 뜻일 뿐이고, 실패한 좌석의 `facts` 에는 `verdict` 가 없다.
 
 **나눠 보낸 페이로드.** 한 좌석에 나눠 보낸 부분들은 그 좌석의 한 판정이다. 모든 부분이 `APPROVE` 일 때만 `APPROVE`, 하나라도 `ERROR` 면 `ERROR`, 그 밖은 가장 나쁜 값(`REJECT` 가 `ITERATE` 보다 나쁘다)이다. 부분끼리는 서로의 내용을 모르므로 좌석 줄에 `분할 N` 을 적는다.
 

package/skills/ralph-qa/references/seat-run.mjs

@@ -601,11 +601,24 @@ const readText = (file) => {
   }
 };
 
+// The standalone verdict lines of an answer. A line inside a code fence (``` or ~~~) is quoted text, not the seat's verdict.
+export function verdictLines(out) {
+  let fence = null;
+  const found = [];
+  for (const line of out.split(/\r?\n/)) {
+    const mark = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (mark && (!fence || (mark[1][0] === fence[0] && mark[1].length >= fence.length))) { fence = fence ? null : mark[1]; continue; }
+    const m = !fence && VERDICT_LINE.exec(line);
+    if (m) found.push(m[1]);
+  }
+  return found;
+}
+
 // What a seat's answer and errors say.
 function factsOf(cli, plan) {
   const out = readText(plan.answer);
   const err = readText(plan.stderr);
-  const facts = { verdicts: out.split(/\r?\n/).map((l) => VERDICT_LINE.exec(l)).filter(Boolean).map((m) => m[1]), empty: !out.trim() };
+  const facts = { verdicts: verdictLines(out), empty: !out.trim() };
   if (cli === "codex") facts.ranModel = (/^model: (\S+)/m.exec(err.split("\n").slice(0, 40).join("\n")) || [])[1] || null;
   if (cli === "gemini") Object.assign(facts, { policyError: err.includes("Policy file error"), apiError: err.includes("Full report") });
   if (cli === "opencode") facts.fallback = err.includes("Falling back to default agent");
@@ -665,10 +678,12 @@ async function runParts(ctx, run, seat, g, parts, base) {
   }
   const last = done[done.length - 1];
   const secs = Math.round(done.reduce((t, x) => t + (x.r.secs || 0), 0) * 10) / 10;
+  // a failed seat has no verdict to count, so its facts carry none (a reader that skips `status` would count it)
+  const shownFacts = (x) => { const f = factsShown(x.f); if (x.why) delete f.verdict; return f; };
   const result = { ...base, status: last.why ? "failed" : "answered", why: last.why, exit: last.r.exit, signal: last.r.signal, secs,
-    answer: last.plan.answer, errors: last.plan.stderr, facts: factsShown(last.f) };
+    answer: last.plan.answer, errors: last.plan.stderr, facts: shownFacts(last) };
   if (!last.why && parts.length > 1) result.facts.verdict = gathered(done.map((x) => x.f.verdicts[0]));
-  if (parts.length > 1) result.parts = done.map((x) => ({ answer: x.plan.answer, errors: x.plan.stderr, why: x.why, facts: factsShown(x.f) }));
+  if (parts.length > 1) result.parts = done.map((x) => ({ answer: x.plan.answer, errors: x.plan.stderr, why: x.why, facts: shownFacts(x) }));
   return result;
 }
 
@@ -838,7 +853,9 @@ async function send(o, ctx) {
     if (thrown) throw thrown.reason;
     const seats = settled.map((x) => x.value);
     if (!a.dryRun) appendFileSync(join(d, "run.md"), seats.filter((x) => x.cliVersion).map((x) => `cli-${x.seat} ${x.cliVersion}\n`).join(""), { mode: 0o600 });
-    const result = { ok: true, ...(a.dryRun ? { dryRun: true } : {}), dir: d, out, bytes: payload.length, scan: 0, unsent: unsentCount(d), seats, declared: declared(run, payload.length, seats, d) };
+    // ok says the send ran; whether seats answered is in `answered`, `failed` and each seat's status
+    const answered = seats.filter((x) => x.status === "answered").length;
+    const result = { ok: true, ...(a.dryRun ? { dryRun: true } : {}), dir: d, out, bytes: payload.length, scan: 0, unsent: unsentCount(d), answered, failed: seats.filter((x) => x.status === "failed").length, seats, declared: declared(run, payload.length, seats, d) };
     if (!a.dryRun) writeResult(d, "send", resultJson("send", result));
     return [result, signals.code(), a.dryRun ? null : d];
   } finally {

package/skills/ralph-qa/references/verifier-probe.mjs

@@ -188,6 +188,8 @@ export const DECISION_REASONS = [
 
 export const CLI_DEFAULT = "@cli-default";
 
+// How a CLI call ended, for a note.
+const callWhy = (res) => (res?.why ? res.why : res?.status === 0 ? "exit 0 with output the probe could not use" : `exit ${res?.status ?? "?"}`);
 const firstLine = (res) => (res?.status === 0 ? String(res.stdout).trim().split("\n")[0] || null : null);
 const absent = (cli) => ({ cli, present: false, decision: "unseated", reason: "cli-absent" });
 const adopt = (seat, model, reason) => ({ ...seat, decision: "adopt", model, reason });
@@ -382,6 +384,8 @@ const rawMcpNames = (lines) => lines.filter((l) => !/^\s*#/.test(l))
 // or the line that opened what is still open), and the strings of each top-level array
 // (`arrays`). Enough for those keys; not a TOML parser.
 export function readToml(text) {
+  // a file there that could not be read (permissions, a folder): nothing it says is known, so it reads as broken
+  if (text?.unreadable) return { values: {}, roots: [], arrays: {}, mcpServers: [], mcpUnread: true, modelKeys: false, broken: true, brokenAt: 0, unreadable: text.unreadable };
   const state = tomlState();
   const lines = String(text ?? "").split(/\r?\n/);
   const isOpen = () => state.open !== null || state.depth > 0;
@@ -457,6 +461,7 @@ export function stripJsonc(text) {
 // { value } for a readable JSONC text, { unreadable: true } for a broken one, {} when absent.
 function readJsonc(text) {
   if (text == null) return {};
+  if (text.unreadable) return { unreadable: true };
   try {
     const value = JSON.parse(stripJsonc(String(text)));
     return value && typeof value === "object" && !Array.isArray(value) ? { value } : { unreadable: true };
@@ -530,7 +535,7 @@ function codexConfig(world) {
     mcpUnread: layers.some((l) => l.mcpUnread),
     modelKeys: layers.some((l) => l.modelKeys),
     broken: layers.some((l) => l.broken),
-    brokenAt: layers.map((l, k) => (l.broken ? `${files[k]} line ${l.brokenAt}` : null)).filter(Boolean),
+    brokenAt: layers.map((l, k) => (!l.broken ? null : l.unreadable ? `${files[k]} (not readable: ${l.unreadable})` : `${files[k]} line ${l.brokenAt}`)).filter(Boolean),
   };
 }
 
@@ -555,6 +560,8 @@ function mcpBlockedSeat(seat, conf, notes) {
 const SEAT_KEYS = ["notify", "otel", "mcp_servers", "web_search", "tools", "analytics", "features", "hooks",
   "sandbox_mode", "sandbox_workspace_write", "approval_policy"];
 
+const unreadAt = (read) => (read.unreadable ? `could not be read (${read.unreadable})` : `could not be read to its end (line ${read.brokenAt})`);
+
 // The unseated seat when the managed file sets one of those keys, or could not be read to its
 // end (a line read short may set one); null otherwise.
 function managedBlockedSeat(seat, world, notes) {
@@ -562,7 +569,7 @@ function managedBlockedSeat(seat, world, notes) {
   const read = readToml(world.readFile(CODEX_MANAGED));
   const keys = read.roots.filter((k) => SEAT_KEYS.includes(k));
   if (!keys.length && !read.broken) return null;
-  notes.push(`${CODEX_MANAGED} ${keys.length ? `sets ${keys.join(", ")}` : `could not be read to its end (line ${read.brokenAt})`}, which codex applies over the seat's -c flags: the seat cannot hold its guards`);
+  notes.push(`${CODEX_MANAGED} ${keys.length ? `sets ${keys.join(", ")}` : unreadAt(read)}, which codex applies over the seat's -c flags: the seat cannot hold its guards`);
   return { ...seat, decision: "unseated", reason: "cli-call-failed" };
 }
 
@@ -583,7 +590,7 @@ function requirementsBlockedSeat(seat, world, notes) {
   const allows = (k) => SEAT_ALLOWS[k] !== undefined && (read.arrays[k] ?? []).includes(SEAT_ALLOWS[k]);
   const keys = read.roots.filter((k) => !GUARD_FREE.includes(k) && !allows(k));
   if (!keys.length && !read.broken) return null;
-  notes.push(`${CODEX_REQUIREMENTS} ${keys.length ? `sets ${keys.join(", ")}` : `could not be read to its end (line ${read.brokenAt})`}, which codex holds over the seat's -c, --disable and -s flags: the seat cannot hold its guards`);
+  notes.push(`${CODEX_REQUIREMENTS} ${keys.length ? `sets ${keys.join(", ")}` : unreadAt(read)}, which codex holds over the seat's -c, --disable and -s flags: the seat cannot hold its guards`);
   return { ...seat, decision: "unseated", reason: "cli-call-failed" };
 }
 
@@ -653,10 +660,18 @@ function codexSeat(flag, { world, runtime, authorFamilies }) {
   const notes = [];
   const conf = codexConfig(world);
   const configured = vetConfigured(safeOnly([conf.cfg.model], "config.toml", notes)[0], authorFamilies, notes);
-  const catalog = readCatalog(world.run("codex", ["debug", "models", "--bundled"]), notes) ?? [];
+  const listed = world.run("codex", ["debug", "models", "--bundled"]);
+  const read = readCatalog(listed, notes);
+  const catalog = read ?? [];
   const sorted = sortModels([...catalog, configured], authorFamilies);
-  const version = firstLine(world.run("codex", ["--version"]));
+  const ran = world.run("codex", ["--version"]);
+  // a version line has a version number in it; an error text on stdout with exit 0 is not one
+  const version = /\d+\.\d+/.test(firstLine(ran) ?? "") ? firstLine(ran) : null;
+  if (!read) notes.push(`codex debug models --bundled gave no catalog (${callWhy(listed)})`);
+  if (!version) notes.push(`codex --version gave no version (${callWhy(ran)})`);
   const seat = { cli: "codex", present: true, version, configured, candidates: sorted.independent, unclassified: sorted.unclassified, mcpServers: conf.mcpServers };
+  // both calls failed: this codex does not run here (not logged in, broken install, killed), so it is not a seat
+  if (!read && !version) return withNotes({ ...seat, decision: "unseated", reason: "cli-call-failed" }, notes);
   const refused = legacyProfileSeat(seat, conf.cfg, notes) ?? managedBlockedSeat(seat, world, notes)
     ?? requirementsBlockedSeat(seat, world, notes) ?? mcpBlockedSeat(seat, conf, notes);
   if (refused) return withNotes(refused, notes);
@@ -710,8 +725,10 @@ function geminiPoliciesDir(world) {
 // seat's read-only tools rest on that flag: such a seat is not seated.
 function geminiPolicySeat(seat, world, notes) {
   const dir = geminiPoliciesDir(world);
-  if (!world.listDir(dir).some((f) => f.endsWith(".toml"))) return null;
-  notes.push(`gemini ignores --admin-policy while ${dir} holds policies: the seat cannot be held to its read-only tools`);
+  const list = world.listDir(dir);
+  if (list && !list.some((f) => f.endsWith(".toml"))) return null;
+  notes.push(list ? `gemini ignores --admin-policy while ${dir} holds policies: the seat cannot be held to its read-only tools`
+    : `the probe could not list ${dir}: gemini ignores --admin-policy while it holds policies, so the seat cannot be shown to keep to its read-only tools`);
   return { ...seat, decision: "unseated", reason: "cli-call-failed" };
 }
 
@@ -835,7 +852,8 @@ const opencodeCache = (world) => join(world.env.XDG_CACHE_HOME || join(world.hom
 function catalogProviders(world) {
   const file = join(opencodeCache(world), "models.json");
   const read = readJsonc(world.readFile(file));
-  return read.value ? new Set(Object.keys(read.value)) : null;
+  // an emptied copy ({}) lists no provider: it says nothing about which ones models.dev knows
+  return read.value && Object.keys(read.value).length ? new Set(Object.keys(read.value)) : null;
 }
 
 // The models the config lists are all opencode can run only when enabled_providers names
@@ -953,18 +971,20 @@ function realWorld() {
     platform: process.platform,
     env: process.env,
     which: onPath,
+    // null when the file is not there; { unreadable } when it is but cannot be read, which is not the same as absent
     readFile: (path) => {
       try {
         return readFileSync(path, "utf8");
-      } catch {
-        return null;
+      } catch (e) {
+        return e.code === "ENOENT" || e.code === "ENOTDIR" ? null : { unreadable: e.code || "error" };
       }
     },
+    // [] when the folder is not there; null when it is but cannot be listed
     listDir: (path) => {
       try {
         return readdirSync(path);
-      } catch {
-        return [];
+      } catch (e) {
+        return e.code === "ENOENT" || e.code === "ENOTDIR" ? [] : null;
       }
     },
     run: (cmd, args, env = {}) => {
@@ -978,11 +998,13 @@ function realWorld() {
       const r = spawnSync(viaCmd ? `"${exe}"` : exe, args, {
         encoding: "utf8",
         timeout: 15000,
+        // a CLI that ignores SIGTERM would hold spawnSync past its time limit
+        killSignal: "SIGKILL",
         maxBuffer: 64 * 1024 * 1024,
         shell,
         env: { ...process.env, ...(viaCmd ? { NoDefaultCurrentDirectoryInExePath: "1" } : {}), ...env },
       });
-      return { status: r.status, stdout: r.stdout ?? "" };
+      return { status: r.status, stdout: r.stdout ?? "", why: r.error ? (r.error.code === "ETIMEDOUT" ? "timed out" : r.error.code) : r.signal ? `killed by ${r.signal}` : null };
     },
   };
 }

package/skills/remains/SKILL.md

@@ -92,7 +92,7 @@ argument-hint: "[기준 커밋] [--no-boxes]"
    - `noTests` 는 시험이 하나도 돌지 않았다는 뜻이라 통과가 아니라 미검증이다.
    - 한 OS 에서만 실패하면, 제품의 결함은 버그로, 시험이 실행 환경을 잘못 가정한 것은 하자로 적는다.
 
-박스에 둔 것은 `run` 이 끝날 때 지운다. 시간 초과, 연결 끊김, 중단(SIGINT, SIGTERM) 때는 박스에서 시작한 프로세스를 먼저 끝낸다. Linux, macOS 는 `mktemp -d` 로 만든 개인 폴더를 쓴다. 지우지 못하면 결과의 `cleaned` 가 `false` 이고, 그 박스를 하자로 적는다.
+박스에 둔 것은 `run` 이 끝날 때 지운다. 시간 초과, 연결 끊김, 중단(SIGINT, SIGTERM) 때는 박스에서 시작한 프로세스를 먼저 끝낸다. Linux, macOS 는 `mktemp -d` 로 만든 개인 폴더를 쓴다. 보통은 `/tmp` 아래이고, `runAs` 박스는 `/var/lib` 아래다. `runAs` 계정의 HOME 도 그 안에 있어서, 임시 폴더를 거부하는 도구(teamwork 등)의 시험도 그대로 돈다. 지우지 못하면 결과의 `cleaned` 가 `false` 이고, 그 박스를 하자로 적는다.
 알려진 한계: 이중 fork 로 프로세스 트리를 벗어난 프로세스는 끝나지 않는다. `pgrep` 이 없는 박스에서는 기록된 프로세스 하나만 끝난다.
 
 ### 등록 파일

package/skills/remains/scripts/boxes.mjs

@@ -27,7 +27,11 @@ const FIELDS = new Set(["name", "os", "ssh", "port", "identity", "path", "runAs"
 const SECRETISH = /pass|secret|token|credential/i;
 const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const TARGET = /^[A-Za-z0-9][A-Za-z0-9._-]*@[A-Za-z0-9][A-Za-z0-9.-]*$/;
-const REMOTE_DIR = /^\/tmp\/banker-remains\.[A-Za-z0-9]+$/;
+// Where a box's private folder goes. A runAs box gets one outside the temporary folders, so that the copy and the
+// run account's HOME inside it are not under /tmp: tools that refuse temporary folders (teamwork's Codex home check)
+// would refuse the tests' fixtures there. /var/lib is root's, so only a root login (runAs) makes one there.
+const dirBase = (b) => (b.runAs ? "/var/lib" : "/tmp");
+const remoteDir = (b) => new RegExp(`^${dirBase(b).replace(/\//g, "\\/")}\\/banker-remains\\.[A-Za-z0-9]+$`);
 // What ssh and scp print about the connection itself, as opposed to what the remote command prints.
 const SSH_ERR = /^(ssh|scp): |Connection (closed|refused|reset|timed out)|Host key verification failed|Permission denied \(|Could not resolve hostname|No route to host|Broken pipe/m;
 const UPLOAD_MS = 10 * 60 * 1000;
@@ -153,8 +157,8 @@ function winSteps(b, name) {
   };
 }
 
-// Linux and macOS work in the private folder `mktemp -d` made. A root login hands the run to runAs, with a
-// HOME of its own. Ending a run takes the process tree under the recorded id first, then the folder.
+// Linux and macOS work in the private folder `mktemp -d` made (under /tmp, or /var/lib for runAs). A root login
+// hands the run to runAs, with a HOME of its own inside that folder. Ending a run takes the process tree under the recorded id first, then the folder.
 function posixSteps(b, name, dir) {
   const go = b.runAs
     ? `mkdir -p "$D/home" && chown -R ${b.runAs} "$D" && runuser -u ${b.runAs} -- env HOME="$D/home" sh "$D/run.sh"`
@@ -227,10 +231,10 @@ const sshFailed = (r) => (r.status === null && !r.timedOut) || (r.status === 255
 
 async function makeDir(b, exec) {
   if (b.os === "win32") return { dir: null };
-  const r = await exec("ssh", [...sshBase(b), b.ssh, "mktemp -d /tmp/banker-remains.XXXXXXXX"], { timeoutMs: PROBE_MS });
+  const r = await exec("ssh", [...sshBase(b), b.ssh, `mktemp -d ${dirBase(b)}/banker-remains.XXXXXXXX`], { timeoutMs: PROBE_MS });
   const dir = String(r.stdout || "").trim();
   if (r.status !== 0) return { error: lastLine(r.stderr) || "ssh 실패" };
-  return REMOTE_DIR.test(dir) ? { dir } : { error: `mktemp -d 가 예상과 다른 경로를 냈습니다: ${dir.slice(0, 80)}` };
+  return remoteDir(b).test(dir) ? { dir } : { error: `mktemp -d 가 예상과 다른 경로를 냈습니다: ${dir.slice(0, 80)}` };
 }
 
 async function attempt(b, plan, exec, files, steps) {
@@ -265,22 +269,37 @@ export async function runOnBox(b, plan, exec) {
 
 // Started from the home folder with git -C: Windows looks for a program in the working folder first, so a git.exe
 // inside the folder worked on never runs.
-function git(cwd, args) {
-  const r = spawnSync("git", ["-C", resolve(cwd), ...args], { cwd: runDir(), encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
-  if (r.status !== 0) throw new Error(`git ${args.filter((a) => !a.includes("=")).join(" ")} 실패: ${lastLine(r.stderr) || r.error?.message || ""}`);
+function git(cwd, args, env = process.env) {
+  const r = spawnSync("git", ["-C", resolve(cwd), ...args], { cwd: runDir(), env, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`git ${gitWords(args)} 실패: ${lastLine(r.stderr) || r.error?.message || ""}`);
   return r.stdout;
 }
 
+// The command words for a message: global options (-c key=value, --no-optional-locks) are left out.
+export const gitWords = (args) => args.filter((a, i) => a !== "-c" && args[i - 1] !== "-c" && !a.startsWith("--no-optional-locks")).join(" ");
+
 // The commit to send. `worktree` is a commit object made from the tracked files as they are now
 // (git stash create: no stash entry, no change to the work tree). Untracked files are never sent.
-function resolveTree(repo, ref) {
-  const status = git(repo, ["status", "--porcelain", "--untracked-files=all"]).split("\n").filter(Boolean);
+// Neither step writes the repository's index: status takes no optional lock, and stash create works on a copy of
+// the index (GIT_INDEX_FILE), so two runs at once, or a git command of the user's, do not meet on index.lock.
+export function resolveTree(repo, ref) {
+  const status = git(repo, ["--no-optional-locks", "status", "--porcelain", "--untracked-files=all"]).split("\n").filter(Boolean);
   const untracked = status.filter((l) => l.startsWith("??")).length;
   if (ref !== "worktree") {
     return { sha: git(repo, ["rev-parse", "--verify", `${ref}^{commit}`]).trim(), untracked, modified: status.length - untracked };
   }
-  const made = git(repo, ["-c", "user.name=banker-remains", "-c", "user.email=banker-remains@localhost", "stash", "create"]).trim();
-  return { sha: made || git(repo, ["rev-parse", "HEAD"]).trim(), untracked, modified: 0 };
+  const tmp = join(tmpdir(), `banker-remains-index-${randomBytes(8).toString("hex")}`);
+  mkdirSync(tmp, { mode: 0o700 });
+  try {
+    const index = resolve(repo, git(repo, ["rev-parse", "--git-path", "index"]).trim());
+    const copy = join(tmp, "index");
+    if (existsSync(index)) copyFileSync(index, copy);
+    const env = { ...process.env, GIT_INDEX_FILE: copy };
+    const made = git(repo, ["-c", "user.name=banker-remains", "-c", "user.email=banker-remains@localhost", "stash", "create"], env).trim();
+    return { sha: made || git(repo, ["rev-parse", "HEAD"]).trim(), untracked, modified: 0 };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
 }
 
 function testFiles(repo, sha) {