@code-yeongyu/senpi-codemode 2026.10.31-1 → 2026.10.31-2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [2026.10.31-2] - 2026-10-31
+
+### Breaking Changes
+
+### Added
+
+- The eval prompt's `Host:` line honors the test-only `SENPI_TEST_WORKSTATION` pin (the same variable and shape coding-agent's workstation facts read, #4662): its CPU model and core count replace the real ones, so a harness driving the CLI gets the same prompt bytes on every host; unset or empty, nothing changes ([#4837](https://github.com/code-yeongyu/senpi/pull/4837))
+- The same pin's optional `repoRoot: {from, to}` field shows the bun-1-4 skill path under the checkout `from` under the synthetic root `to` instead, so the checkout location does not reach the prompt either (#5067) ([#4837](https://github.com/code-yeongyu/senpi/pull/4837))
+
+### Changed
+
+- The bundled `bun-1-4` skill is now `bun`: its capability map and operating rules cover Bun 1.4.1-1.4.4 (`bun check`, `bun fmt`, `Bun.FetchSession`, HTTP/2 in `Bun.serve`, offline installs) and the Bun.$ / Bun.spawn / bun test practices learned in agent sessions, with a new `references/session-recipes.md`; the eval prompt's pointer names the `bun` skill and also fires before a cell that spawns a process or runs tests ([#5158](https://github.com/code-yeongyu/senpi/pull/5158))
+
+### Fixed
+
+- An eval call that leaves out `language`, `code` or `summary` now gets one clear error per missing field (naming the enabled languages) instead of a list of every schema branch it failed ([#5150](https://github.com/code-yeongyu/senpi/pull/5150))
+- `eval` `peek`/`stop` with a mistyped `cell_id` now suggests the one close known cell id ([#5153](https://github.com/code-yeongyu/senpi/issues/5153))
+
+### Removed
+
 ## [2026.10.31-1] - 2026-10-31
 
 ### Breaking Changes

package/README.md

@@ -42,7 +42,7 @@ task-tool names are known.
   JS runtime (`node`/`bun`).
 - JavaScript import rewriting for supported local modules and package imports
   in the persistent JS worker (Bun when senpi runs on bun, Node.js otherwise).
-- On a Bun >= 1.4 kernel the eval prompt names the bundled `bun-1-4` skill as
+- On a Bun >= 1.4 kernel the eval prompt names the bundled `bun` skill as
   MUST READ before the first js cell; node kernels keep the Node.js wording.
 - GPT models receive a terse `eval` prompt dialect that prioritizes composing
   active tools through `tool.<name>(args)` and documents detach-on-timeout.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.31-1",
+	"version": "2026.10.31-2",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -33,15 +33,15 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.31-1",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.31-2",
 		"quickjs-wasi": "3.6.2",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.31-1"
+		"@code-yeongyu/senpi": "2026.10.31-2"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.31-1"
+		"@code-yeongyu/senpi": "2026.10.31-2"
 	},
 	"keywords": [
 		"senpi",

package/src/extension/host-facts.ts

@@ -1,10 +1,88 @@
 import * as os from "node:os";
+import * as path from "node:path";
 import { jsRuntimeLabel } from "./runtime-info.ts";
 
+/**
+ * Test-only host pin (senpi#4660): the same `SENPI_TEST_WORKSTATION={"cpuModel":string,"cores":int,"kernel":string}`
+ * coding-agent's workstation.ts reads. Its CPU model and core count replace the real ones in the `Host:` line, so a
+ * harness driving the real CLI gets the same prompt bytes on every host. Its optional
+ * `"repoRoot":{"from":absolute path,"to":absolute path}` (senpi#5067) shows a path under the checkout `from` under `to`
+ * where the eval prompt renders it (`pinnedDisplayPath`). Unset (or empty) in every production launch.
+ */
+const WORKSTATION_ENV = "SENPI_TEST_WORKSTATION";
+
+interface PinnedWorkstation {
+	readonly cpuModel: string;
+	readonly cores: number;
+	readonly repoRoot?: { readonly from: string; readonly to: string };
+}
+
+function pinnedRepoRoot(value: unknown): { readonly from: string; readonly to: string } | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	if (Object.keys(value).sort().join(",") !== "from,to" || !("from" in value) || !("to" in value)) return undefined;
+	const { from, to } = value;
+	if (typeof from !== "string" || typeof to !== "string" || !path.isAbsolute(from) || !path.isAbsolute(to))
+		return undefined;
+	return { from, to };
+}
+
+function pinnedWorkstation(env: NodeJS.ProcessEnv): PinnedWorkstation | undefined {
+	const value = env[WORKSTATION_ENV];
+	if (value === undefined || value === "") return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		parsed = undefined;
+	}
+	const keys = typeof parsed === "object" && parsed !== null ? Object.keys(parsed).sort().join(",") : "";
+	if (
+		typeof parsed === "object" &&
+		parsed !== null &&
+		!Array.isArray(parsed) &&
+		(keys === "cores,cpuModel,kernel" || keys === "cores,cpuModel,kernel,repoRoot") &&
+		"cpuModel" in parsed &&
+		"cores" in parsed &&
+		"kernel" in parsed
+	) {
+		const { cpuModel, cores, kernel } = parsed;
+		const repoRoot = "repoRoot" in parsed ? pinnedRepoRoot(parsed.repoRoot) : undefined;
+		if (
+			!("repoRoot" in parsed && repoRoot === undefined) &&
+			typeof cpuModel === "string" &&
+			cpuModel !== "" &&
+			typeof kernel === "string" &&
+			kernel !== "" &&
+			typeof cores === "number" &&
+			Number.isInteger(cores) &&
+			cores >= 1
+		)
+			return { cpuModel, cores, ...(repoRoot === undefined ? {} : { repoRoot }) };
+	}
+	throw new Error(
+		`${WORKSTATION_ENV} must be a JSON object {"cpuModel": non-empty string, "cores": positive integer, "kernel": non-empty string, optional "repoRoot": {"from": absolute path, "to": absolute path}}, got ${JSON.stringify(value)}`,
+	);
+}
+
+/**
+ * `filePath` as the eval prompt should show it: under the test-only `repoRoot` pin, a path inside the pinned checkout
+ * (`from`) is shown under `to`. Every other path, and every path when the pin is unset, is returned unchanged.
+ * Only for rendering: reads keep using the real path.
+ */
+export function pinnedDisplayPath(filePath: string, env: NodeJS.ProcessEnv = process.env): string {
+	const root = pinnedWorkstation(env)?.repoRoot;
+	if (root === undefined) return filePath;
+	if (filePath === root.from) return root.to;
+	const prefix = root.from.endsWith(path.sep) ? root.from : root.from + path.sep;
+	return filePath.startsWith(prefix) ? path.join(root.to, filePath.slice(prefix.length)) : filePath;
+}
+
 /** The one-line host description the eval prompt shows (platform, CPU, cores, JS runtime). */
-export function hostLine(): string {
-	const cpu = os.cpus()[0]?.model?.trim();
-	return [`${os.platform()} ${os.arch()}`, cpu, `${os.availableParallelism()} cores`, jsRuntimeLabel()]
+export function hostLine(env: NodeJS.ProcessEnv = process.env): string {
+	const pinned = pinnedWorkstation(env);
+	const cpu = pinned ? pinned.cpuModel : os.cpus()[0]?.model?.trim();
+	const cores = pinned ? pinned.cores : os.availableParallelism();
+	return [`${os.platform()} ${os.arch()}`, cpu, `${cores} cores`, jsRuntimeLabel()]
 		.filter((part): part is string => !!part)
 		.join(" \u00b7 ");
 }

package/src/extension/skill-contribution.ts

@@ -28,10 +28,10 @@ export function bunVersionSupportsSkill(version: string | undefined): boolean {
 	return major > 1 || (major === 1 && minor >= 4);
 }
 
-const BUN_SKILL_PACKAGE_RELATIVE_PATH = join("skill", "bun-1-4", "SKILL.md");
+const BUN_SKILL_PACKAGE_RELATIVE_PATH = join("skill", "bun", "SKILL.md");
 
 /**
- * Absolute path of the bundled bun-1-4 SKILL.md, or undefined (logged once) when it is not shipped.
+ * Absolute path of the bundled bun SKILL.md, or undefined (logged once) when it is not shipped.
  *
  * A compiled Bun binary has no readable module-relative asset, so resolution falls back to the
  * codemode sidecar shipped next to the executable, exactly as the Ruby and Julia kernel runners do.
@@ -41,7 +41,7 @@ export function bundledBunSkillPath(
 	baseDir: string = BUN_SKILL_BASE_DIR,
 	environment: CodemodeRuntimeAssetEnvironment = {},
 ): string | undefined {
-	const localPath = join(baseDir, "..", "skill", "bun-1-4", "SKILL.md");
+	const localPath = join(baseDir, "..", "skill", "bun", "SKILL.md");
 	const candidate = resolveCodemodeRuntimeAsset(localPath, BUN_SKILL_PACKAGE_RELATIVE_PATH, environment);
 	if (existsSync(candidate)) return candidate;
 	if (!loggedMissingBunSkill) {
@@ -58,14 +58,14 @@ export function bundledBunSkillPath(
 			BUN_SKILL_PACKAGE_RELATIVE_PATH,
 		);
 		console.error(
-			`[senpi-codemode] bundled bun-1-4 skill not found at ${localPath} or ${sidecarPath}; skipping contribution`,
+			`[senpi-codemode] bundled bun skill not found at ${localPath} or ${sidecarPath}; skipping contribution`,
 		);
 	}
 	return undefined;
 }
 
 /**
- * Absolute path of the bundled bun-1-4 SKILL.md when it is active for this process:
+ * Absolute path of the bundled bun SKILL.md when it is active for this process:
  * the in-process js eval kernel itself runs bun >= 1.4 (`process.versions.bun`) and the
  * asset is shipped. A node kernel never activates it, regardless of any bun binary on PATH.
  */
@@ -77,7 +77,7 @@ export function activeBunSkillPath(
 	return bundledBunSkillPath(baseDir);
 }
 
-/** Builds the `resources_discover` handler that contributes the active bun-1-4 skill, if any. */
+/** Builds the `resources_discover` handler that contributes the active bun skill, if any. */
 export function createBunSkillDiscoverHandler(
 	getKernelBunVersion: BunKernelVersionSource = kernelBunVersion,
 	baseDir?: string,

package/src/prompt/eval-prompt-template.ts

@@ -29,7 +29,7 @@ Host: {{hostLine}}. Cells execute here. Size \`parallel(thunks)\` pools to its c
 A cell that outlives the foreground window detaches and keeps running; further cells on the same language queue behind it in submission order on the same kernel (state is shared, execution is serial) while other languages run at once, up to {{maxDetachedCells}} background cells per session; each detached cell completes as one notification. Do not re-run a detached or queued cell; read, cancel or enumerate them with \`eval({ action: "peek" | "stop", cell_id })\` / \`eval({ action: "list" })\`; list shows live and recently settled cells across languages without consuming notifications. Its own execution time is capped at {{runBudgetSeconds}}s (queue time and time inside host tool calls are not charged; the hard limit stays wall-clock from submission; raise \`timeout\` only for a declared long run), and a killed js cell that cannot settle restarts its kernel with every global lost.
 
 {{#if py}}Python runs on a live event loop: use top-level \`await\`; \`asyncio.run(…)\` raises.{{/if}}
-{{#if js}}{{#if jsBun}}JS runs in-process on Bun {{jsVersion}}: top-level \`await\`/\`return\` work; \`Bun.*\` builtins available, including \`new Bun.WebView()\`, a headless browser (navigate/click/evaluate/screenshot) to reach for before \`curl\` or a browser CLI when a page needs JS, a login, or a screenshot. Shell out through \`Bun.$\` or \`Bun.spawn\`, never \`Bun.spawnSync\`: a synchronous child blocks the worker and cannot be interrupted.{{#if bunSkillPath}} Before a cell that installs a package, spawns a server or PTY, or starts a long run, read the bun-1-4 skill at {{bunSkillPath}}; its builtins replace the npm packages you would otherwise install.{{/if}}{{else}}JS runs under Node.js worker: top-level \`await\`/\`return\` work; \`fetch\`/\`Buffer\` available.{{/if}}{{/if}}
+{{#if js}}{{#if jsBun}}JS runs in-process on Bun {{jsVersion}}: top-level \`await\`/\`return\` work; \`Bun.*\` builtins available, including \`new Bun.WebView()\`, a headless browser (navigate/click/evaluate/screenshot) to reach for before \`curl\` or a browser CLI when a page needs JS, a login, or a screenshot. Shell out through \`Bun.$\` or \`Bun.spawn\`, never \`Bun.spawnSync\`: a synchronous child blocks the worker and cannot be interrupted.{{#if bunSkillPath}} Before a cell that installs a package, spawns a process, server or PTY, runs tests, or starts a long run, read the bun skill at {{bunSkillPath}}: its builtins replace the npm packages you would otherwise install, and it lists the Bun.$ / Bun.spawn / bun test traps that cost past sessions hours.{{/if}}{{else}}JS runs under Node.js worker: top-level \`await\`/\`return\` work; \`fetch\`/\`Buffer\` available.{{/if}}{{/if}}
 {{#if rb}}Ruby: synchronous; helper options are keyword args{{#if spawns}} (e.g. \`output("id", limit: 2)\`){{/if}}; the last expression auto-displays unless it is \`nil\`, an assignment, or a definition (like IRB).{{/if}}
 {{#if jl}}Julia: synchronous; helper options are standard keyword args{{#if spawns}} (e.g. \`output("id", limit=2)\`){{/if}}; the last expression auto-displays unless it is an assignment or a definition (like the Julia REPL).{{/if}}
 On error, fix and re-run only the failing step; a normal error keeps state, while a timeout or stop message says whether the kernel restarted.

package/src/prompt/eval-prompt.ts

@@ -1,5 +1,6 @@
 import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import { DEFAULT_MAX_DETACHED_CELLS, DEFAULT_RUN_BUDGET_SECONDS } from "../config/settings.ts";
+import { pinnedDisplayPath } from "../extension/host-facts.ts";
 import type { EvalRuntimeInfo } from "../tool/types.ts";
 import { EVAL_PROMPT_TEMPLATE } from "./eval-prompt-template.ts";
 
@@ -29,7 +30,7 @@ export interface EvalPromptOptions {
 	readonly hostLine?: string;
 	/** Identity of the in-process js kernel; a bun runtime swaps the Node.js worker line for the Bun one. */
 	readonly jsRuntime?: EvalRuntimeInfo;
-	/** Absolute path of the active bun-1-4 skill; rendered as a MUST READ pointer only on a bun kernel. */
+	/** Absolute path of the active bun skill; rendered as a MUST READ pointer only on a bun kernel. */
 	readonly bunSkillPath?: string;
 	/** Kill deadline for a cell's own execution time, as configured; the description states it. */
 	readonly runBudgetSeconds?: number;
@@ -105,7 +106,8 @@ export function buildEvalPrompt(
 		hostLine: options.hostLine ?? "",
 		jsBun: options.jsRuntime?.name === "bun",
 		jsVersion: options.jsRuntime?.version ?? "",
-		bunSkillPath: options.bunSkillPath ?? "",
+		// pinnedDisplayPath: the test-only checkout pin (senpi#5067); the path itself unless SENPI_TEST_WORKSTATION pins it.
+		bunSkillPath: options.bunSkillPath === undefined ? "" : pinnedDisplayPath(options.bunSkillPath),
 		runBudgetSeconds: String(options.runBudgetSeconds ?? DEFAULT_RUN_BUDGET_SECONDS),
 		maxDetachedCells: String(options.maxDetachedCells ?? DEFAULT_MAX_DETACHED_CELLS),
 		kernelPreludeDocs: (options.kernelPreludes ?? []).map((prelude) => prelude.documentation).join("\n"),

package/src/skill/bun/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: bun
+description: "Read before a js eval cell that spawns a process, server or PTY, installs a package, or starts a long run, and before any bun -e, script, server, CLI, test, typecheck, format, bundle, or package-management work: this session's eval js kernel runs Bun 1.4+. Bun 1.4.x builtins replace 20+ npm deps and dev tools — check here BEFORE installing or running tsc/tsgo, prettier/oxfmt, sharp, puppeteer/playwright (scraping), cheerio, marked, node-cron, node-pty, execa/zx, concurrently, serve-static, tar, json5, fast-xml-parser, string-width, dotenv, keytar, aws-sdk (S3/R2) — and before writing Bun.$ / Bun.spawn / bun test code: the traps that cost past sessions hours are listed here. Triggers: eval js, bun, Bun.$, Bun.spawn, Bun.serve, bun test, bun check, bun fmt, bun build, bun install, image resize, headless browser, markdown, cron, PTY, secrets."
+---
+
+# Bun 1.4.x — Use the Builtins First
+
+Bun 1.4.0 (Aug 2026) through 1.4.4 (Oct 2026) ships builtins and CLIs that replace most utility npm packages and several dev tools. **Before adding a dependency, spawning a tool, or writing a workaround, check the map below — if Bun ships it, use the builtin.** Version tags (`[v1.4.3]`) in the references give exact minimums; dated notes `(2026-10-25)` mark facts measured in our own sessions. Release posts: <https://bun.com/blog/bun-v1.4> … <https://bun.com/blog/bun-v1.4.4>.
+
+## Capability map — what you can do now
+
+| You want to... | Use | Replaces | Ref = `references/<name>.md` |
+|---|---|---|---|
+| Type-check a TS project: tsc-identical errors, 3-6x faster, no `typescript` install | `bun check --no-script`, `bun run/test/build --check` | tsc, tsgo | dev-tooling |
+| Format with your Prettier/oxfmt config | `bun fmt --no-script` (`--check`, `--changed`, `--staged`) | prettier, oxfmt, lint-staged | dev-tooling |
+| Run shell commands from JS, no `/bin/sh` | `` Bun.$`...` `` → `.nothrow().quiet().text()/.json()/.lines()` | execa, zx, shelljs | session-recipes |
+| Spawn with timeout / PTY / IPC; measure a child | `Bun.spawn({ env: process.env, timeout, killSignal, terminal, ipc })`, `proc.resourceUsage()` | node-pty, tree-kill, pidusage | session-recipes |
+| Keep tokens out of files, argv and env dumps | `Bun.secrets.get/set` (OS keychain), `--env-file=/dev/stdin` | keytar, dotenv | session-recipes |
+| Resize/convert/rotate images | `Bun.file(p).image().resize().webp().write()` | sharp | runtime-apis |
+| Headless browser: navigate, click, screenshot, evaluate, CDP | `new Bun.WebView()` | puppeteer, playwright (scraping) | runtime-apis |
+| Scrape or rewrite HTML by CSS selector, streaming | `new HTMLRewriter().on("a[href]", { element })` | cheerio, jsdom (scraping) | runtime-apis |
+| Markdown → HTML / React / ANSI | `Bun.markdown.html() / .react() / .ansi()` | marked, react-markdown, glow | runtime-apis |
+| Schedule cron jobs | `Bun.cron()` | node-cron | runtime-apis |
+| Run package scripts concurrently, glob-matched | `bun run --parallel "build:*"` | concurrently, npm-run-all | runtime-apis |
+| Parse JSON5 / JSONL / JSONC / XML / TOML / YAML; tarballs; globs | `Bun.JSON5/.JSONL/.JSONC/.XML/.TOML/.YAML`, `Bun.Archive`, `Bun.Glob` | json5, ndjson, jsonc-parser, fast-xml-parser, @iarna/toml, js-yaml, tar, fast-glob | runtime-apis |
+| ANSI-aware terminal text; table rendering | `Bun.stringWidth/sliceAnsi/wrapAnsi/stripANSI()`, `Bun.inspect.table()` | string-width, slice-ansi, wrap-ansi, strip-ansi, cli-table | runtime-apis |
+| Hash, UUID v7, semver, deep-equal, gzip/zstd, which | `Bun.hash/CryptoHasher/password`, `randomUUIDv7`, `Bun.semver`, `deepEquals`, `gzipSync/zstdCompressSync`, `Bun.which` | uuid, semver, lodash.isequal, pako, which | runtime-apis |
+| Postgres / MySQL / SQLite, Redis, S3-compatible (R2) clients | `Bun.SQL`, `bun:sqlite`, `Bun.RedisClient`, `Bun.S3Client` / `s3://` | pg, mysql2, better-sqlite3, ioredis, aws-sdk | runtime-apis |
+| Serve a static dir (ETag/Range/304 handled) | `Bun.serve({ routes: { "/x/*": { dir } } })` | express.static, serve-static, sirv | http-networking |
+| HTTP/2 + HTTP/3 server; fetch protocol/compress/proxy; per-client pools | `http2: true`, `http3: true`, `fetch(url, { protocol, compress, proxy })`, `new Bun.FetchSession()` | undici Agent | http-networking |
+| Stream a download to disk; replay a request as curl | `Bun.write(path, await fetch(url))`, `BUN_CONFIG_VERBOSE_FETCH=curl` | pipeline + createWriteStream | http-networking |
+| Tests across CPU workers / CI shards / changed files / flaky retry | `bun test --parallel --shard=1/3 --changed=main --retry` | jest/vitest infra | test |
+| Kill "passes alone, fails in suite" bugs; hunt flakes | `bun test --isolate`, `--rerun-each N`, `--only-failures` | vitest default behavior | test |
+| Single-file executables with embedded assets and profile-guided startup; feature flags; in-memory bundling; metafile; React Compiler | `bun build --compile --asset ./public --bytecode-order`, `bun:bundle feature()`, `files:{}`, `metafile: true`, `--react-compiler` | pkg hacks, esbuild define/plugins, babel-plugin-react-compiler | build |
+| Diff package versions, fix vulns, dedupe/prune, licenses, explain a dep | `bun pm diff`, `bun audit fix`, `bun dedupe`, `bun prune`, `bun pm licenses`, `bun why` | npm-diff, npm audit fix, npm ls | install |
+| Offline / cached installs; Docker layers; CI cache; 7x faster CI | `bun install --offline\|--prefer-offline`, `bun pm fetch`, `bun pm cache pack\|unpack`, `linker = "isolated"` | pnpm store | install |
+| Profile CPU/heap/bundle as grep-able Markdown | `bun --cpu-prof-md`, `--heap-prof-md`, `bun build --metafile-md` | Chrome DevTools round-trip | dev-tooling |
+| Run untrusted JS without eval / `new Function` / FFI | `--disallow-code-generation-from-strings=strict`, `--no-ffi-cc` | vm2 | security |
+| Run Playwright, vitest, Next.js 16, OpenTelemetry, dd-trace; `undici`, `node-fetch`, `ws` | they now just work (the last three load Bun's builtin even when installed) | Node.js | node-compat-platforms |
+
+Free wins (no code change): 2x lower CPU, 13-48% less server memory, 2-2.5x faster startup — numbers in [performance](references/performance.md).
+
+## Operating rules — 2 to 6 are what past sessions paid for
+
+1. **Eval-first, builtin-first.** The `eval` js kernel runs on Bun (that is why this skill is present): call `Bun.*` APIs directly inside js cells and reach for `bash` or a spawned `bun` only for CLI surfaces (`bun test`, `bun build`, `bun pm`) or work that needs a separate process. The Replaces column above is a ban list for new dependencies in production code, test helpers and one-off scripts alike.
+2. **Anything that must outlive a cell starts outside it.** The kernel SIGKILLs every `Bun.spawn` child when its cell settles, so browsers, daemons, dev servers, remote `ssh` jobs and slow git hooks start through `tool.monitor({ command })` or `tool.bash({ run_in_background: true })`; a stopped long `Bun.$` cell restarts the kernel and loses every global, so helpers live in an importable file.
+3. **`Bun.$` runs one command with array-interpolated args; real shell syntax goes to bash.** `${"a b"}` is ONE argument, `$?`/`$VAR` are literal, `for`/`until`/heredocs are parse errors or silent `command not found` with rc 0, and `VAR=x cmd` is not applied to a binary — each of these produced a false-green gate. Use `` $`cmd ${[args]}`.nothrow().quiet() `` for a command and `Bun.spawn(["bash", "-c", script], { env: process.env, stdin: "ignore" })` for a script.
+4. **Every `Bun.spawn` passes `env: process.env`, and re-spawns Bun as `process.execPath`.** An env-less child gets the environment the process STARTED with (runtime HOME/TMPDIR edits never arrive), and `"bun"` from PATH has resolved to three different shims on our machines. Give a child that reads stdin `stdin: "ignore"` or an explicit end, or it waits for EOF forever.
+5. **`bun test` gets its timeout on the command line and exact paths with `./`.** `--timeout N` is the only budget that reaches every file (a preload's `setDefaultTimeout` covers the first file, bunfig's is ignored); a timeout SIGTERMs every child the test spawned, so a database started in `beforeAll` dies with it; `bun test path.ts` without `./` is a substring filter. The full table is in [test](references/test.md) — read it before writing or debugging a suite.
+6. **Measure with the Bun the work targets.** The kernel's `Bun.version`, the shell's `bun --version` and a repo's pinned Bun (CI `bun-version`, `devDependencies.bun`) differ on one machine and 1.4.2 vs 1.4.3 changed test outcomes, so evidence runs use the pin; probe a feature in an empty directory, because `bun check`/`bun fmt`/`bun lint` otherwise run a same-named package.json script. Installs: `CI=1`, visible output, and after `--ignore-scripts` run `node node_modules/bun/install.js` — [install](references/install.md) lists why.
+7. **Read the matching reference before using an unfamiliar API** — signatures and caveats (`Bun.markdown` HTML is unsanitized, HTTP/3 is experimental, `writer({ append: true })` truncated a results file) live there, not here; [session-recipes](references/session-recipes.md) holds the rest of the session-learned traps.
+8. **Upgrading a project or debugging behavior that changed?** Read [breaking-changes](references/breaking-changes.md) first — 1.4.0 changed YAML/TOML strictness, `.xml`/`.css` imports, `Bun.$` globbing and fetch headers; 1.4.1-1.4.4 changed `Bun.Glob` parsing, WebSocket close timing and `bun install` flag handling.
+9. **TLS errors after upgrade are usually intentional** — 1.4.x tightened certificate verification across `fetch`, `tls.connect`, `Bun.connect`, `RedisClient`, `Bun.SQL`. See [security](references/security.md) before loosening anything.

package/src/skill/{bun-1-4 → bun}/references/breaking-changes.md

@@ -1,6 +1,29 @@
-# Upgrading to Bun 1.4 — Behavior Changes
+# Upgrading to Bun 1.4.x — Behavior Changes
 
-Blog: [#upgrading-to-1-4](https://bun.com/blog/bun-v1.4#upgrading-to-1-4). Most code is unaffected. Scan the Top 5, then the table for whatever subsystem you touched.
+Blog: [#upgrading-to-1-4](https://bun.com/blog/bun-v1.4#upgrading-to-1-4), then the 1.4.1-1.4.4 posts. Most code is unaffected. Scan the Top 5, then the 1.4.1-1.4.4 table, then the 1.4.0 tables for whatever subsystem you touched.
+
+## 1.4.1 → 1.4.4 — changes that bit our repos
+
+| Change | Version | Migration |
+|---|---|---|
+| `Bun.Glob`: `?( )`, `*( )`, `+( )`, `@( )`, `!( )` and `{1..3}` are extglob/ranges (were literal); applies to `--filter`, `workspaces`, `files`, `sideEffects` | 1.4.4 | a pattern with `*(1).txt` now means "zero or more 1"; escape as `*[(]1).txt`. An 11-group `{a,b}` allowlist that 1.4.3 refused matched on 1.4.4 — re-test auth boundaries after a Bun bump (2026-10-25) |
+| `bun check` / `bun fmt` run a same-named package.json script first | 1.4.3 / 1.4.4 | `--no-script` for the builtin; probe features in an empty directory, since `bun lint --help` exits 0 via a script on a Bun with no linter (2026-10-22) |
+| `bun install` rejects unknown flags (was: silently ran) | 1.4.4 | fix the typo; npm/Yarn/pnpm spellings are translated |
+| Linux installs skip the other libc's native builds; `file:` folders are hardlinked (were per-file symlinks) | 1.4.4 | tools that filter optional deps by os/cpu must also filter `libc` (desktop stage-lock broke); "no links" checks see hardlinks |
+| WebSocket client `close` waits for the closing handshake: `1005` not `1000` without a code, `1006` after 30 s; failed connects fire `error` then `close(1006)` | 1.4.4 | await the `close` event; `BUN_CONFIG_WS_CLOSE_TIMEOUT`; `ws.terminate()` to skip |
+| `ws` is a port of ws 8.22: an `'error'` without a listener is an uncaught exception; `close` reason is a `Buffer`; no default idle timeout/ping on `ws` servers; `maxPayload` 100 MiB | 1.4.4 | add `'error'` listeners everywhere |
+| Servers request a client certificate only with `requestCert: true` (`ca` alone no longer does) | 1.4.4 | set both for mTLS |
+| `Bun.hash()`/`CryptoHasher`/`crypto.hash()` of a `Bun.file`/S3 file throw `TypeError` (was: hash of empty input) | 1.4.4 | read the bytes first |
+| `Bun.SQL` ignores `PASSWORD`; `affectedRows` is a number on PG/SQLite (was `null`); `sql.array([...])` no longer casts to `JSON[]` | 1.4.4 | `PGPASSWORD` / URL / option |
+| `fetch()` TLS name comes from the URL, not a custom `Host` header | 1.4.1 | `tls.servername` for IP + name |
+| `fs.rmdir(p, { recursive: true })` works again (1.4.0 threw) | 1.4.1 | — |
+| `--disallow-code-generation-from-strings=strict` also blocks plugins returning source, macros, and on-disk `.ts/.js` inside compiled binaries | 1.4.4 | return exports objects from plugins |
+| Coverage counts skipped branches/`await` continuations/implicit constructors as uncovered | 1.4.4 | `% Lines`/`% Funcs` drop; re-check thresholds |
+| PID 1 in a container exits `128 + signal` on Ctrl+C / `docker stop` | 1.4.4 | match on the new code |
+| `bun add -E react@18` writes the installed exact version (was `18`) | 1.4.4 | — |
+| `bun.lock` gains `hasInstallScript` / `libc`; older Bun drops them on save | 1.4.4 | pin one Bun per repo (CI `bun-version`) |
+| Windows: `expect(p).rejects` after a socket close segfaulted the runner in 1.4.3 (upstream fix reverted) | fixed 1.4.4 | stay on 1.4.4+ on Windows CI |
+| Still open on 1.4.4: `fs.rm` ignores `maxRetries`/`retryDelay` (bun#41480); `expect(p).rejects` after a Worker reply deadlocks (bun#37189) | — | explicit retry helper; capture rejections with `.then()` |
 
 ## Top 5 most likely to bite
 
@@ -52,7 +75,6 @@ Blog: [#upgrading-to-1-4](https://bun.com/blog/bun-v1.4#upgrading-to-1-4). Most
 
 | Change | Migration |
 |---|---|
-| `fs.rmdir` rejects `{ recursive: true }` | `fs.rm(path, { recursive: true, force: true })` |
 | `dns.lookup()` uses the system resolver (getaddrinfo) on Linux — split-DNS/VPN names now resolve | `Bun.dns.lookup(name, { backend: "c-ares" })` for old behavior |
 | fs/dns/pbkdf2 callback exceptions are `uncaughtException` (was unhandledRejection) | move the handler |
 | `dgram`: second `bind()` and post-`close()` calls throw synchronously | try/catch |
@@ -72,4 +94,4 @@ Blog: [#upgrading-to-1-4](https://bun.com/blog/bun-v1.4#upgrading-to-1-4). Most
 - `Temporal` defined by default (`BUN_JSC_useTemporal=0` to disable).
 - `bun.lock` is `lockfileVersion: 2`; nested/version-scoped overrides produce v3 (older Bun can't read v3).
 - `bun feedback` removed; `Bun.password.hash()` argon2 requires `memoryCost >= 8`.
-- Full exhaustive list: [Other behavior changes](https://bun.com/blog/bun-v1.4#other-behavior-changes) and the [Changelog](https://bun.com/blog/bun-v1.4#changelog).
+- Full exhaustive lists: [1.4.0 Other behavior changes](https://bun.com/blog/bun-v1.4#other-behavior-changes) and the Bugfixes sections of the [1.4.1](https://bun.com/blog/bun-v1.4.1), [1.4.3](https://bun.com/blog/bun-v1.4.3) and [1.4.4](https://bun.com/blog/bun-v1.4.4) posts.

package/src/skill/{bun-1-4 → bun}/references/build.md

@@ -1,4 +1,12 @@
-# bun build / Bun.build() in 1.4
+# bun build / Bun.build() in 1.4.x
+
+## Compiled-binary rules learned in production (omo ships one)
+
+- **`bun` inside a compiled binary can be the binary itself.** Bun Shell resolves `bun` to `process.execPath` when PATH has no bun; in a `--compile` app that re-runs the app's own entry (argv `["bun", "/$bunfs/root/..."]`), which booted a phantom agent turn (omo#9362). `BUN_BE_BUN=1` makes a compiled executable behave as plain bun, but it propagates to grandchildren; senpi appends a real bun shim to PATH instead. `Bun.spawn(["bun"])` does not fall back (ENOENT).
+- Worker threads do not see main-thread `process.env` writes — env for a kernel worker must travel explicitly.
+- `bun:ffi` `cc()` cannot compile a `.c` file embedded in `$bunfs`; avoid runtime C compilation in shipped binaries (2026-10-26).
+- `--compile` binaries ignore `NODE_COMPILE_CACHE` [v1.4.1] and no longer auto-load `tsconfig.json`/`package.json` from the cwd (`--compile-autoload-tsconfig` / `--compile-autoload-package-json` opt back in); `.env` and `bunfig.toml` still auto-load.
+- `--compile-exec-argv="--disallow-code-generation-from-strings=strict"` bakes runtime flags into the binary; `BUN_OPTIONS` at launch can raise but not lower them.
 
 ## Built-in React Compiler [v1.4.0]
 
@@ -21,6 +29,15 @@ await Bun.build({ entrypoints: ["./src/index.tsx"], optimizeImports: ["antd", "@
 
 `import { Button } from "antd"` skips the hundreds of files behind names you didn't import. Automatic for packages with `"sideEffects": false`; opt others in with `optimizeImports`.
 
+## Smaller output since 1.4.1
+
+- `export * as` groups (zod, Effect, fp-ts) tree-shake to the members you call: zod 4.5 375 KB → 77 KB minified. Namespace objects still accept assignment; `--no-deprecated-namespace-object-setters` makes them getter-only (future default).
+- Dynamic `import()` and `require()` of an ES module tree-shake unused exports when every use reads a named export (`const { z } = await import("zod")` bundles like a static import).
+- `--splitting`: fewer chunks (shared code stays in the entry), `--min-chunk-size=16384` folds tiny side-effect-free chunks, `<link rel="modulepreload">` + `__preload()` are emitted for browser builds (`--no-module-preload` to disable), bundle-wide names shrink minified output ~19%.
+- `--splitting --target bun`: `require()` of an ES module becomes a lazy chunk (startup 23 ms → 11 ms on a 400-module CLI); `--no-split-require` keeps the old inlining.
+- `[hash9]`…`[hash13]` in `naming` widens chunk hashes; two chunks can no longer collide on an 8-char hash [v1.4.3]. `metafile.inputs[*].entryPoint` names the file behind a split `import()` [v1.4.3].
+- `Bun.build({ check: true })` / `bun build --check` type-checks first and writes nothing on a type error [v1.4.3].
+
 ## Compile-time feature flags: bun:bundle [v1.3.5]
 
 Blog: [#compile-time-feature-flags-with-bun-bundle](https://bun.com/blog/bun-v1.4#compile-time-feature-flags-with-bun-bundle)
@@ -72,11 +89,20 @@ bun build ./build/index.js --compile \
 
 Keeps original filenames; `path.join(import.meta.dir, ...)` works. `node:fs` treats `/$bunfs/` as a real tree (`existsSync`, `readdirSync` recursive/withFileTypes, ...), so static-file servers run unmodified inside the binary.
 
-## Bytecode for ES modules [v1.3.9]
+## Bytecode for ES modules [v1.3.9], smaller and PGO-ordered [v1.4.1, v1.4.3]
 
-Blog: [#bytecode-compilation-for-es-modules](https://bun.com/blog/bun-v1.4#bytecode-compilation-for-es-modules)
+Blog: [#bytecode-compilation-for-es-modules](https://bun.com/blog/bun-v1.4#bytecode-compilation-for-es-modules), [1.4.3 #profile-guided-bytecode-layout](https://bun.com/blog/bun-v1.4.3)
+
+`--bytecode --format=esm` (requires `--compile`) enables top-level await, `import.meta`, dynamic imports, and code splitting in bytecode-compiled binaries (previously CJS-only). Bytecode is now ~3x the source size instead of 9x (Claude Code's install: 376 MB → 207 MB) and the cache format is identical on every platform, so cross-compiling with `--bytecode` works and builds are byte-identical [v1.4.1].
+
+```bash
+bun build --compile --bytecode ./cli.ts --outfile myapp
+BUN_BYTECODE_ORDER_OUT=myapp.order ./myapp --help        # run it the way users do; the profile is written on exit
+bun build --compile --bytecode --bytecode-order=myapp.order ./cli.ts --outfile myapp   # cold start 1.01 s → 0.53 s on a large CLI
+```
 
-`--bytecode --format=esm` (requires `--compile`) enables top-level await, `import.meta`, dynamic imports, and code splitting in bytecode-compiled binaries (previously CJS-only).
+- `--bytecode-depth=1` limits ahead-of-time bytecode to shallow functions (rest compile on first call); `--compile-jit-policy <n>` keeps run-once startup code in the interpreter, then `Bun.unsafe.setJITPolicy(1)` once interactive; `--no-optimize-bytecode` skips the optimizer. `bytecodeOrderStats()` from `bun:jsc` reports profile coverage.
+- Text imports (`with { type: "text" }`) are embedded once, pre-encoded: a 3 MB file adds 3 MB to the binary and ~1 MB of memory instead of 6 MB / 12.6 MB [v1.4.1].
 
 ## metafile: true and --metafile-md [v1.3.6 / v1.3.8]
 
@@ -109,6 +135,6 @@ Active when `experimentalDecorators` is off in tsconfig. Classes, methods, field
 
 Reachability walk is now BFS O(V+E); a 20,000-module DAG links in 320ms (was 4.65s). Tree-shaking/TLA/CSS-order passes use explicit stacks, so linear chains of thousands of modules link without stack growth.
 
-## Compile gotcha (v1.3.4 change)
+## Memory and speed [v1.4.1, v1.4.3]
 
-`bun build --compile` binaries no longer auto-load `tsconfig.json` / `package.json` from the runtime cwd. Opt back in with `--compile-autoload-tsconfig` / `--compile-autoload-package-json`. `.env` and `bunfig.toml` still auto-load.
+Bundling three.js x100: 1.83 s → 1.12 s. 800 entry points with `--splitting`: peak RSS 2,121 MB → 276 MB [v1.4.3]. Nested classes and functions keep their names (`Model`, not `Model2`) [v1.4.1].

package/src/skill/bun/references/dev-tooling.md

@@ -0,0 +1,67 @@
+# Bun 1.4.x Dev Tooling & Observability
+
+Blog: [#dev-tooling](https://bun.com/blog/bun-v1.4#dev-tooling), [#observability](https://bun.com/blog/bun-v1.4#observability), [1.4.3 bun check](https://bun.com/blog/bun-v1.4.3), [1.4.4 bun fmt](https://bun.com/blog/bun-v1.4.4)
+
+## bun check — TypeScript type checker (replaces tsc / tsgo) [v1.4.3, 1.4-7.8x faster in v1.4.4]
+
+Docs: <https://bun.com/docs/runtime/check>
+
+```bash
+bun check --no-script                 # whole project from the nearest tsconfig.json; every core; no `typescript` install needed
+bun check --no-script src/index.ts    # one file and everything it imports
+bun check --no-script -b              # follow project references, like tsc -b (shares caches across projects)
+bun check --no-script --no-pretty     # one line per error, tsc --pretty false shape (default when piped)
+bun run --check src/index.ts          # type-check, then run (also package.json scripts and --watch)
+bun test --check  /  bun build --check   # no tests run / nothing is written on a type error; Bun.build({ check: true })
+```
+
+- **`bun check` runs the package.json `check` script when one exists** (senpi, omo and the desktop repo all have one), and `bun fmt` likewise runs a `fmt` script. Measured on 1.4.4: `bun check` in such a project printed the script's output and exited 0 with a type error present. `--no-script` reaches the builtin.
+- Port of typescript-go: same errors, same codes, same positions as `tsc` 7.0.2 (51,210/51,210 conformance baselines; 0 mismatches across 72 misconfigured OSS repos). A difference from `tsc` is a Bun bug.
+- Type-check only: no emit, no `.d.ts`, no language server — LSP diagnostics still come from the editor's TypeScript.
+- Any compiler option works as a flag and overrides tsconfig: `bun check --noUncheckedIndexedAccess`.
+
+## bun fmt — Prettier-compatible formatter (replaces prettier, oxfmt, lint-staged) [v1.4.4]
+
+Docs: <https://bun.com/docs/format>
+
+```bash
+bun fmt --no-script                   # format the project; reads .prettierrc*, prettier.config.*, .editorconfig, .prettierignore, .oxfmtrc*
+bun fmt --no-script --check           # list files that need formatting; exit 1 if any
+bun fmt --no-script --changed[=origin/dev]   # only files that differ from the default branch (or a ref)
+bun fmt --no-script --staged          # pre-commit: format staged files and re-stage them
+bun fmt --doctor                      # how Bun reads your config; which prettier plugins/packages you can uninstall
+```
+
+- JS/TS/JSX, CSS/SCSS/Less, HTML/Vue/Svelte/Angular, JSON/JSONC/JSON5, YAML, TOML, Markdown/MDX, GraphQL, Handlebars, plus embedded code. 99.1% byte-identical to Prettier 3.9.9 on its own test suite; 286x faster.
+- Built in: import sorting, Tailwind class sorting (uses the project's `tailwindcss`), `package.json` key sorting, Svelte. Unsupported plugins (e.g. `prettier-plugin-jsdoc`) print an error, skip their files, exit 2; Astro-style plugin languages fall back to the project's Prettier.
+- `[fmt]` in bunfig.toml takes every Prettier option by the same name (`bun fmt --init`); `--debug-check` fails if formatting changed a file's meaning.
+
+## Markdown profilers — built for terminals and LLMs
+
+```bash
+bun --cpu-prof-md ./app.ts     # CPU profile as Markdown: hot functions by self time,
+                               # call tree, who-calls-whom. grep it, paste into a bug or an LLM.
+bun --heap-prof-md ./app.ts    # heap profile as Markdown: total size, types by retained size,
+                               # largest objects, retention chains. Includes grep recipes in the header.
+bun build ./src/index.ts --outdir ./dist --metafile-md=./dist/meta.md   # bundle-size analysis as Markdown
+```
+
+- `bun --cpu-prof` / `--heap-prof` still write `.cpuprofile` / V8-compatible `.heapsnapshot` for Chrome DevTools / VS Code.
+- `BUN_CPU_PROFILE=1` turns on the CPU profiler for a process you cannot pass flags to (e.g. a framework-spawned worker).
+- **Agent workflow: when a Bun process is slow or leaking, run the `-md` variants and read the report directly — no DevTools round-trip.**
+
+## Async stack traces [v1.4.0]
+
+Errors from async native APIs (`fs.promises`, `Bun.file()`, S3, DNS, crypto, `fetch`) point at the `await` in your code, not native frames.
+
+Process lifetime (`--no-orphans`), env files, `BUN_OPTIONS`, memory measurement and `BUN_CONFIG_VERBOSE_FETCH=curl` are in [session-recipes](session-recipes.md).
+
+## Watch and hot reload
+
+`bun --watch app.ts` restarts the process on file change (`--watch-kill-signal=SIGTERM` picks the signal, `--no-clear-screen` keeps scrollback); `bun --hot app.ts` swaps modules in place without restarting — `Bun.serve` keeps its port, `Bun.SQL` keeps its connections [v1.4.4], and `import.meta.hot.data` carries state across reloads. `bun test --watch` re-runs affected files.
+
+## APM / tracing works now
+
+- **`node:inspector`**: a `Session` can start/stop CPU profiles while the app runs (`Profiler.start`/`Profiler.stop`).
+- **Datadog**: `dd-trace` traces requests; `@datadog/pprof` profiles continuously (required V8 C++ APIs implemented).
+- **OpenTelemetry**: `@opentelemetry/instrumentation-http` and `-fs` export spans; `shimmer` and `require-in-the-middle` can patch bundled code.