fix(runtime): env-overridable sandbox hook/action timeout to de-flake CI (#3259)

[os-zhuang]

Closes #3259.

Problem

The QuickJS sandbox enforces a wall-clock deadline per hook/action invocation (250ms hooks / 5000ms actions). Every invocation compiles a fresh WASM module, and a nested hook compiles another one inside the parent's budget — so on an oversubscribed CI runner (4-vCPU, turbo --concurrency=4 + vitest workers) that fixed VM-creation cost alone intermittently tripped the 250ms hook default even while the VM was still making progress. It surfaced as hook '…' exceeded timeout of 250ms on PRs that never touched the sandbox path (the variable pump count — 215 vs 246 — before the same wall-clock deadline is the signature of a load flake, not a logic bug).

9498eb4 (#3264) bumped the individually-named tests to a 10s budget, but that's whack-a-mole: the shared 250ms floor kept resurfacing on other tests (quickjs-runner 'lvl4', per the issue comment), and the production runners in app-plugin.ts still use the stock default with no way to tune it.

Fix

Implements the issue's suggested direction #1 — make the deadline env-overridable (OS_SANDBOX_*, per the OS_{DOMAIN}_{NAME} convention / Prime Directive #9) — so the floor is raised once, deployment-wide, instead of per call site.

• @objectstack/types — new resolveSandboxTimeoutMs(kind, fallback) (the repo's "single decision point" env pattern):
  • OS_SANDBOX_HOOK_TIMEOUT_MS — default hook budget (ms)
  • OS_SANDBOX_ACTION_TIMEOUT_MS — default action budget (ms)
  • Only a positive integer is honored; unset / empty / non-numeric / non-positive keeps the built-in fallback, so behaviour is byte-for-byte unchanged when the vars are absent.
• @objectstack/runtime — QuickJSScriptRunner resolves its hook/action defaults through it. Precedence unchanged: explicit constructor option → env → built-in default; and a body's own declared timeoutMs still wins over the resolved default. This automatically covers the four production runners in app-plugin.ts.
• CI — OS_SANDBOX_HOOK_TIMEOUT_MS=10000 set for the whole workflow so the loaded-runner flake can't recur across any sandbox test (present or future). Genuine hangs stay bounded by each test's own vitest timeout. Production keeps 250ms/5000ms unless it opts in.
• Tests — pinned the quickjs-runner timeout-resolution suite's runner to an explicit 250ms so its assertions are independent of the CI env var; added a dedicated env-override suite + resolveSandboxTimeoutMs unit tests.
• Docs — corrected the QuickJSScriptRunner class docstring's stale "we pool runtimes" claim (Prime Directive chore: version packages #10, declared ≠ enforced): runtimes are deliberately per-invocation — precisely the VM-creation cost this flake is about.

Verification

• @objectstack/types env tests — 25 passed
• @objectstack/runtime sandbox suite — 54 passed, run both with and with OS_SANDBOX_HOOK_TIMEOUT_MS=10000 set (simulating CI); the pinned/env-managed tests behave identically either way
• eslint clean; @objectstack/types and @objectstack/runtime builds (tsup DTS typecheck) green

Out of scope (already noted in the issue): the separate @objectstack/http-conformance vitest-worker EPIPE transient (direction #3).

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 19, 2026 11:40am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/runtime, @objectstack/types.

16 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/api/index.mdx (via @objectstack/runtime)
• content/docs/api/wire-format.mdx (via @objectstack/runtime)
• content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
• content/docs/concepts/north-star.mdx (via packages/runtime)
• content/docs/data-modeling/drivers.mdx (via @objectstack/runtime)
• content/docs/deployment/index.mdx (via @objectstack/runtime)
• content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
• content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
• content/docs/deployment/vercel.mdx (via @objectstack/runtime)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/runtime)
• content/docs/permissions/authentication.mdx (via @objectstack/runtime)
• content/docs/plugins/packages.mdx (via @objectstack/runtime, @objectstack/types)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/index.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/runtime)
• content/docs/releases/implementation-status.mdx (via @objectstack/runtime)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

按 Prime Directive #10 把长期方案落成了 #3275:Phase 1 改计费语义(脚本 CPU 预算 + 宽松墙钟兜底,解开"容忍慢机器"与"约束失控脚本"共用一个旋钮的矛盾)→ Phase 2 去 asyncify(deferred+pump 重构后已无挂起 WASM 栈的需求,保留每调用独立模块)→ Phase 3 预编译 WebAssembly.Module、每次只实例化;并明确记录了拒绝共享单例模块的安全理由(共享线性内存会把 QuickJS 引擎级 bug 的爆炸半径扩大到跨租户)。

本 PR 保持最小止血不扩 scope;Phase 1 在本 PR 合并后开工。届时 CI 里的 OS_SANDBOX_HOOK_TIMEOUT_MS=10000 地板有望撤掉,env 旋钮保留作慢硬件的运维手段。

---

Generated by Claude Code