diff --git a/packages/code-runtime/code-runtime-python/README.i18n.yaml b/packages/code-runtime/code-runtime-python/README.i18n.yaml
index 34651facd9..35f7700e97 100644
--- a/packages/code-runtime/code-runtime-python/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-python/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-python/README.md
-README.md: 7b116c4d51df44e0db519fdf0fd73a1776dfb4f1
-README.zh.md: 2f367d6bde6d79163be9e45e2bdea61ab0f62958
+README.md: eab1adebcf3189d7bec812dd4b1a16a3e9d0a78c
+README.zh.md: d52545f3fcc8884341f3fdfad0d387808eafcd62
diff --git a/packages/code-runtime/code-runtime-python/README.md b/packages/code-runtime/code-runtime-python/README.md
index 7b116c4d51..eab1adebcf 100644
--- a/packages/code-runtime/code-runtime-python/README.md
+++ b/packages/code-runtime/code-runtime-python/README.md
@@ -116,7 +116,7 @@ These limits define what the package does and does not cover; they are current p
- **An fd-3 frame whose raw length exceeds 64 MiB settles the run as a worker-exit** — `maxLogBytes`/`maxValueBytes` are load-bounded to the same parser cap so an honest child's frames always fit; a model-constructed binding ARGUMENT above 64 MiB (a value with no seam-level budget) trips the same cap — an accepted residual of the OOM guard.
- **A combined log-and-value peak is not modelled by the load gate** — a model daemon thread that keeps writing while the completion value is metered and framed can add the two peaks in a way no gate admits or rejects; the run dies as `worker-exit`, containment holds, and only the failure classification is degraded.
- **A 1-second dual-limit `ulimit -t 1` CPU overrun is reported as `worker-exit`, not a timeout** — when the host starts under a hard CPU limit equal to the soft and that limit is 1, `_clamped` cannot lower the soft, so the kernel SIGKILLs the busy loop and SIGXCPU is never delivered; containment holds, only the classification is degraded.
-- **No byte cap on intermediate binding values** — the implementation remains bounded by structured-clone cost and process memory, and a provider or executor may apply its own fetch cap.
+- **No byte cap on intermediate binding values** — the implementation remains bounded by the lossless-JSON serialization cost and process memory, and a provider or executor may apply its own fetch cap.
### Dev Note
diff --git a/packages/code-runtime/code-runtime-python/README.zh.md b/packages/code-runtime/code-runtime-python/README.zh.md
index 2f367d6bde..d52545f3fc 100644
--- a/packages/code-runtime/code-runtime-python/README.zh.md
+++ b/packages/code-runtime/code-runtime-python/README.zh.md
@@ -116,7 +116,7 @@ kind: "package-reference"
- **原始长度超过 64 MiB 的 fd-3 帧会让本次运行以 worker-exit 结算**——`maxLogBytes`/`maxValueBytes` 在加载期被限制到同一解析器上限,因此诚实子进程的帧总能放得下;模型构造的超过 64 MiB 的 binding 实参(一个在 seam 层没有预算的值)会触发同一上限——这是该 OOM 防护的已接受残余。
- **组合日志与值的峰值不被加载门建模**——持续写入的模型 daemon 线程与完成值计量、分帧相加的峰值没有任何门会放行或拒绝;运行以 `worker-exit` 告终,隔离成立,只有失败分类降级。
- **1 秒双限 `ulimit -t 1` CPU 超限被报告为 `worker-exit` 而非 timeout**——当宿主在一个与软限相等的硬 CPU 限下启动且该限为 1 时,`_clamped` 无法下调软限,内核在同一 tick SIGKILL 忙循环,SIGXCPU 永远不会送达;隔离成立,只有分类降级。
-- **中间 binding 值没有字节上限**——实现仍受 structured-clone 成本与进程内存约束,提供方或执行器可能应用自己的获取上限。
+- **中间 binding 值没有字节上限**——实现仍受无损 JSON 序列化成本与进程内存约束,提供方或执行器可能应用自己的获取上限。
### 开发备注
diff --git a/packages/code-runtime/code-runtime-python/src/index.ts b/packages/code-runtime/code-runtime-python/src/index.ts
index 85e1320fdf..d1f795ff15 100644
--- a/packages/code-runtime/code-runtime-python/src/index.ts
+++ b/packages/code-runtime/code-runtime-python/src/index.ts
@@ -14,7 +14,7 @@
import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
import { once } from 'node:events'
-import { accessSync, copyFileSync, constants as fsConstants, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { accessSync, copyFileSync, constants as fsConstants, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { delimiter, dirname, isAbsolute, join } from 'node:path'
import { fileURLToPath } from 'node:url'
@@ -403,11 +403,14 @@ function resolvePythonBin(bin: string): string {
// the working directory, and the returned candidate must be an absolute
// path — spawn() resolves a relative pythonBin against the host CWD, which
// is outside the seam contract.
- /* v8 ignore next -- normal PATHs carry no empty or relative segment. */
if (dir === '' || !isAbsolute(dir)) continue
const candidate = join(dir, bin)
try {
accessSync(candidate, fsConstants.X_OK)
+ // A directory passes X_OK too, so require a regular file: a PATH entry
+ // named like the interpreter (e.g. a `python3` directory) must not be
+ // chosen over a later real interpreter.
+ if (!statSync(candidate).isFile()) continue
return candidate
} catch {
// Not executable here; try the next PATH entry.
@@ -790,7 +793,7 @@ export class PythonCodeRuntime extends CodeRuntime {
}
const limit = FRAME_PARSE_CAP_BYTES - FRAME_ENVELOPE_BYTES
if (this.config[key] > limit) {
- throw new Error(`dsh-code-runtime-python: config.${key} must not exceed ${limit} (a payload that large cannot cross the fd-3 frame PARSER, which drops raw frames past ${FRAME_PARSE_CAP_BYTES} bytes before decoding to bound host memory — a larger budget would admit a config whose honest child frames the host then silently discards, stranding the run to the wall clock), got ${String(this.config[key])}`)
+ throw new Error(`dsh-code-runtime-python: config.${key} must not exceed ${limit} (a payload that large cannot cross the fd-3 frame PARSER, which rejects raw frames past ${FRAME_PARSE_CAP_BYTES} bytes before decoding to bound host memory — a larger budget would admit a config whose honest child frames the host then rejects as a worker-exit), got ${String(this.config[key])}`)
}
// Reject a log budget too small to honor: the truncation marker alone
// must serialize within the budget, or a marker-only truncated run
@@ -871,8 +874,11 @@ export class PythonCodeRuntime extends CodeRuntime {
}
/**
- * Execute one program in a fresh Python subprocess. Program outcomes resolve
- * with `result.error`; the method rejects only for seam misuse.
+ * Execute one program in a fresh Python subprocess. Every program outcome —
+ * parse failure, thrown exception, invalid completion, output overflow,
+ * budget expiry, abort, or substrate death — resolves with `result.error` set
+ * (classified by `CodeRunFailure.kind`); the method rejects only for seam
+ * misuse.
*/
async run(request: CodeRunRequest): Promise {
if (this.disposed) throw new Error('dsh-code-runtime-python: run() after disposal')
@@ -1448,12 +1454,21 @@ export class PythonCodeRuntime extends CodeRuntime {
// retained state to one number and cannot be poisoned by a forgery.
let nextCallId = 0
+ // Set by run() when the boot frame is written; the fd-3 handler calls it
+ // on boot-ack to send the run frame (see the seam's boot->boot-ack->run
+ // order). scoped per run. An object holder so the cross-closure
+ // assignment is a property write (eslint's prefer-const cannot see the
+ // reassignment through the closure).
+ const bootAckGate: { run?: () => void } = {}
const handleFrame = (message: ChildToHost): void => {
/* v8 ignore next -- late frame after settlement; defensive against forged post-settlement traffic. */
if (settled) return
switch (message.type) {
case 'boot-ack':
- return // Presently informational.
+ // The child accepted the boot frame (namespaces built); the run
+ // frame goes out now, not with the boot frame.
+ bootAckGate.run?.()
+ return
case 'log':
if (message.truncated === true) {
// The CHILD ledger hit its cap. Its marker is the last log text
@@ -1967,13 +1982,27 @@ export class PythonCodeRuntime extends CodeRuntime {
...namespace.errorClass ? { errorClass: namespace.errorClass } : {},
})),
}
+ // The run frame is sent only after the child's boot-ack: the seam
+ // contract puts `run` after `boot-ack` (the ack confirms the namespaces
+ // were accepted), and sending it earlier would let a boot failure race
+ // the run frame. The ack handler below writes it.
+ let runSent = false
try {
proto.write(`${JSON.stringify(boot)}\n`)
- proto.write(`${JSON.stringify({ type: 'run', program: request.program })}\n`)
} catch (error: unknown) {
finish({ error: { kind: 'worker-exit', message: `failed to boot python subprocess: ${messageOf(error)}` } })
return
}
+ // Register the ack gate with the frame handler before any data arrives.
+ bootAckGate.run = (): void => {
+ if (runSent) return
+ runSent = true
+ try {
+ proto.write(`${JSON.stringify({ type: 'run', program: request.program })}\n`)
+ } catch (error: unknown) {
+ finish({ error: { kind: 'worker-exit', message: `failed to boot python subprocess: ${messageOf(error)}` } })
+ }
+ }
})
}
}