diff --git a/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.i18n.yaml new file mode 100644 index 0000000000..e382100132 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.i18n.yaml @@ -0,0 +1,22 @@ +# Bilingual-pair consistency record for 2026-09-27-pwsh-prompt-tail-grace.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.md +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace: + en: 5e8c5673a0669d9c + zh: c8442a6186288a2a +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/problem: + en: ac4fb08e3203cee9 + zh: 69fcfcb4f8fc0319 +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/decision: + en: 3727656a7fab5543 + zh: a641a52acb2054ea +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/alternatives-considered: + en: 21a9a19b76f42758 + zh: 30a8f5425b59900d +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/consequences: + en: b58904921286a1db + zh: a696c2954d86c04f +/agent-note-a-seen-prompt-marker-keeps-its-own-tail-grace/testing: + en: 9e01d92dae7fdc1d + zh: 666832ec7d9fff38 diff --git a/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.md b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.md new file mode 100644 index 0000000000..9b7cacdc4d --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.md @@ -0,0 +1,31 @@ +# Agent Note: A seen prompt marker keeps its own tail grace + +Status: implemented + +English | [中文](2026-09-27-pwsh-prompt-tail-grace.zh.md) + +## Problem + +Windows sessions on the self-hosted lane settled one or two of seven sends on the controlled prompt and charged the silence tier for the rest (2026-09-25/26, issue #2487). The exact readiness evidence is the controlled prompt's printable tail after the OSC `133;D` marker, and the bound on waiting for it was `idleSilenceMs + handoffGraceMs`. A native Windows probe shows the render arrives as two pty chunks: the marker alone, then the five-byte `dsh> ` 2-28 ms later (56 renders), with nothing printable after any prompt and no terminal queries in the output. The marker is written by the shell's own prompt function and the tail by the same render, so a tail that arrives past the bound means the host stalled that delivery, not that the prompt is absent. The session settled `inferred_idle` anyway, and each such send cost the tool call roughly three seconds. + +## Decision + +`dsh-terminal-bash` gains a validated `promptTailGraceMs` configuration field, default `0`. While a send has seen the prompt marker and its printable tail has not arrived, the silence bound becomes `idleSilenceMs + handoffGraceMs + promptTailGraceMs`; every other bound, wait reason, and code path is unchanged. Zero reproduces the previous bound exactly, so an upgrade changes no deployment's behaviour. The persistent pwsh Loader-composition case sets 5000 ms, because the hosts whose stalls the field is for are exactly the ones that run it, and its assertion (at least six `stdin_read` settlements, no `inferred_idle`) then measures the controlled-prompt path instead of the host's delivery timing. `validateConfig` accepts zero for this field — the one numeric bound whose zero is a documented value — and rejects negative or fractional values. + +## Alternatives considered + +**Raise the default instead of adding a field.** Rejected: it trades one fixed cost for another on every host. A marker whose tail never arrives (a stray marker from a child, a broken prompt function) would then fall back that much later everywhere, while the timing that matters differs per deployment. + +**Make the observation sticky: once the exact tail was seen, let later output stand.** Rejected: the tail rule exists to prove the marker was followed by the prompt text rather than by a command's output, and a sticky flag would settle a send while that command is still printing. + +**Wait for the tail up to the absolute `timeoutMs` once a marker was seen.** Rejected: a prompt that never completes its render would hang every send until the tool deadline instead of falling back after a bounded silence, and the send budget belongs to the caller. + +**Detect the stall in the test and retry the send.** Rejected: retries hide which tier settled a send, and the durable fix belongs where the evidence is interpreted, not where it is measured. + +## Consequences + +A deployment whose console renderer stalls keeps those sends on the exact path by setting `promptTailGraceMs`; the default path is bit-for-bit the previous bound, so the negative control — the same delayed tail with the field at zero — still settles `inferred_idle`. The tolerance applies only after a marker was seen: a missing prompt keeps the plain silence bound, so the regression the Loader-composition case pins (a lost prompt must fail) is still caught, and a marker whose tail never arrives falls back one configured interval later. + +## Testing + +`packages/terminal/terminal-bash/tests/session.spec.ts` pins both directions with fake timers: with `promptTailGraceMs` set, a marker whose tail arrives after the plain bound stays pending and then settles `stdin_read`; with the field at zero, the same delivery settles `inferred_idle`. `packages/terminal/terminal-bash/tests/config.spec.ts` accepts zero and rejects negative or fractional values. `packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts` carries the end-to-end evidence on native Windows: with every session's prompt tail withheld for four seconds the case fails at the default zero with `expected 4 to be greater than or equal to 6`, and passes with the configured tolerance. diff --git a/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md new file mode 100644 index 0000000000..2a88b90028 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md @@ -0,0 +1,31 @@ +# Agent Note: 已看到的提示符标记保留自己的尾部宽限 + +Status: implemented + +[English](2026-09-27-pwsh-prompt-tail-grace.md) | 中文 + +## Problem + +自托管 lane 上的 Windows 会话在七次 send 中只有一到两次按受控提示符结算,其余都要支付静默层(2026-09-25/26,issue #2487)。精确的就绪证据是 OSC `133;D` 标记之后受控提示符的可打印尾部,而等待它的上界是 `idleSilenceMs + handoffGraceMs`。原生 Windows 探测表明该渲染以两个 pty 分块到达:先是标记本身,2–28 毫秒后是 5 字节的 `dsh> `(56 次渲染),任何提示符之后都没有可打印文本,输出中也没有终端查询。标记由 shell 自己的 prompt 函数写出、尾部由同一次渲染写出,因此尾部晚于上界到达意味着宿主机拖慢了这次投递,而不是提示符缺失。会话此前仍会按 `inferred_idle` 结算,每次这样的 send 让工具调用多付约三秒。 + +## Decision + +`dsh-terminal-bash` 新增一个经过校验的 `promptTailGraceMs` 配置字段,默认 `0`。当某次 send 已看到提示符标记而其可打印尾部尚未到达时,静默上界变为 `idleSilenceMs + handoffGraceMs + promptTailGraceMs`;其他上界、等待原因与代码路径均不变。零精确复现此前的上界,因此升级不改变任何部署的行为。持久 pwsh 的 Loader 组合用例设置 5000 毫秒,因为需要该字段的宿主机正是运行该用例的那些,而其断言(至少六次 `stdin_read` 结算、不含 `inferred_idle`)由此度量受控提示符路径,而不是宿主机的投递时序。`validateConfig` 允许该字段取零——这是唯一一个零为文档化取值的数值上界——并拒绝负数与小数。 + +## Alternatives considered + +**不加字段,直接提高默认值。** 不采纳:那是把一种固定成本换成另一种,且对所有宿主机生效。尾部永不到达的标记(子进程打印的杂散标记、损坏的 prompt 函数)会在所有地方都多等那么久,而真正重要的时序因部署而异。 + +**让观测变为粘性:一旦看到精确尾部,后续输出不再使其失效。** 不采纳:尾部规则的存在就是为了证明标记之后跟着的是提示符文本而不是命令输出;粘性标志会在命令仍在打印时结算该 send。 + +**看到标记后一直等到绝对 `timeoutMs`。** 不采纳:渲染永不完成的提示符会让每次 send 都挂到工具截止时间,而不是在有界静默后回退,而 send 预算属于调用方。 + +**在测试里检测停摆并重试该 send。** 不采纳:重试会掩盖究竟是哪一层结算的,而持久的修复属于解释证据的地方,而不是测量证据的地方。 + +## Consequences + +控制台渲染器会停摆的部署通过设置 `promptTailGraceMs` 让这些 send 留在精确路径上;默认路径与此前的上界逐位一致,因此负控——同样的尾部延迟、字段为零——仍然按 `inferred_idle` 结算。该宽限只在看到标记之后生效:提示符缺失时保持普通静默上界,所以 Loader 组合用例所固定的回归(提示符丢失必须失败)仍会被抓住,而尾部永不到达的标记只会晚一个配置区间回退。 + +## Testing + +`packages/terminal/terminal-bash/tests/session.spec.ts` 用假定时器固定两个方向:设置 `promptTailGraceMs` 时,尾部晚于普通上界到达的标记保持挂起,随后按 `stdin_read` 结算;字段为零时,同样的投递按 `inferred_idle` 结算。`packages/terminal/terminal-bash/tests/config.spec.ts` 接受零并拒绝负数或小数。`packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts` 承载原生 Windows 上的端到端证据:把每个 session 的提示符尾部扣留四秒时,该用例在默认零值下以 `expected 4 to be greater than or equal to 6` 失败,而在配置了该宽限后通过。 diff --git a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.i18n.yaml b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.i18n.yaml index c52ccdc078..3e4c2f6895 100644 --- a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.i18n.yaml @@ -18,5 +18,5 @@ en: 13db32f9da19d87b zh: 48081fc7035dea45 /agent-note-windows-lane-observations-wait-on-the-state-they-read/deferred: - en: 68baa2f8c114d646 - zh: 5ca029c62a288b14 + en: 18dc81f98375fb04 + zh: e30413cd3d201b80 diff --git a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.md b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.md index 4eb4ed92ae..e0218a4d5f 100644 --- a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.md +++ b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.md @@ -32,4 +32,4 @@ Both plugin-manager record cases now observe the record while the run is in flig ## Deferred -The loader-composition failure of 2026-09-25/26 remains unexplained. On Windows `isStdinWaiting` returns false and `foregroundPgid` returns the shell pid, so `stdin_read` can only come from the controlled-prompt tail; the three failing runs settled one or two of seven sends on that prompt, and their durations (17.5 s, 20.9 s against 4.7 s healthy) match one silence tier per degraded send while every output assertion passed. A fourth run timed out at the case bound. Native Windows reproduction was unavailable for this change (the local guest rejected its guest-operations credentials), so the assertion, the session's readiness path, and the prompt installation are unchanged; the next failure now names the tiers each send settled on. +The loader-composition failure of 2026-09-25/26 is an environment-sensitive readiness window, not a product logic error, and the product now owns a documented tolerance for it: the [prompt tail grace decision](../bug-fix/2026-09-27-pwsh-prompt-tail-grace.md). On Windows `isStdinWaiting` returns false and `foregroundPgid` returns the shell pid, so `stdin_read` can only come from the controlled-prompt tail. A native Windows probe (Windows 11 ARM64 guest, 8 vCPU, with the readiness probe enabled) shows the fast path is deterministic when delivery is normal: every prompt render is the OSC marker alone in one pty chunk followed by a five-byte `dsh> ` chunk 2-28 ms later (56 renders), nothing printable follows any prompt, the output carries no terminal queries, and 21 runs (baseline, six CPU burners, emulated x64, four concurrent pty-heavy instances, and Windows PowerShell 5.1 as the shell) settled all seven sends on the prompt, six `stdin_read` plus the `exit` command's `session_exit`. Withholding each session's prompt tail for four seconds reproduces the reported failure exactly: `expected 4 to be greater than or equal to 6` with `["inferred_idle","stdin_read","stdin_read","stdin_read","stdin_read","session_exit","inferred_idle"]`, the degraded settles carrying `promptSeen` true, `promptTextSeen` false, an empty tail and `idleFor` 3301/3313 ms (exactly the configured bound), 22.1/21.9 s against 17.5/20.9 s in CI, and every output assertion still passing. The CI trigger itself was not reproduced locally, so this case keeps its assertion and supplies `promptTailGraceMs` in its composition: it measures the controlled-prompt path rather than the host's delivery timing, and it still fails when no prompt marker appears at all. diff --git a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.zh.md b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.zh.md index e471e76383..079ae65451 100644 --- a/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.zh.md +++ b/.agents/notes/implemented/testing/2026-09-27-observation-waits-on-observed-state.zh.md @@ -32,4 +32,4 @@ loader-composition 的结算层级断言把 `JSON.stringify(settleReasons)` 作 ## Deferred -loader-composition 于 2026-09-25/26 的失败仍未解释。在 Windows 上 `isStdinWaiting` 返回 false,`foregroundPgid` 返回 shell 自身的 pid,因此 `stdin_read` 只能来自受控提示符尾部;三次失败运行中七次 send 只有一到两次按该提示符结算,而其耗时(17.5 秒、20.9 秒,对照健康时的 4.7 秒)与「每次退化 send 支付一层静默」相符,同时所有输出断言都通过。第四次运行在用例上界处超时。本次改动无法获得原生 Windows 复现(本机 guest 拒绝其 guest operations 凭据),因此断言、会话的就绪路径与提示符安装均未改动;下一次失败会指明各次 send 结算在哪些层级上。 +loader-composition 于 2026-09-25/26 的失败是一个对投递时序敏感的就绪窗口,而不是 product 逻辑错误;product 现在为它拥有一个文档化的容忍度:[提示符尾部宽限决策](../bug-fix/2026-09-27-pwsh-prompt-tail-grace.zh.md)。在 Windows 上 `isStdinWaiting` 返回 false、`foregroundPgid` 返回 shell 自身的 pid,因此 `stdin_read` 只能来自受控提示符尾部。原生 Windows 探测(Windows 11 ARM64 guest,8 vCPU,启用就绪探测)表明只要投递正常,快路径就是确定的:每次提示符渲染都是 OSC 标记独占一个 pty 分块,紧随其后的下一个分块是 5 字节的 `dsh> `,间隔 2–28 毫秒(56 次渲染),任何提示符之后都没有可打印文本,输出中也没有终端查询;21 次运行(基线、6 个 CPU burner、模拟 x64、4 个并发 pty 实例、以及以 Windows PowerShell 5.1 作为 shell)全部七次 send 都按提示符结算——六次 `stdin_read` 加 `exit` 命令的 `session_exit`。把每个 session 的提示符尾部扣留 4 秒可以精确复现上报的失败:`expected 4 to be greater than or equal to 6`,`settleReasons` 为 `["inferred_idle","stdin_read","stdin_read","stdin_read","stdin_read","session_exit","inferred_idle"]`,退化的结算带着 `promptSeen` 为 true、`promptTextSeen` 为 false、空尾部与 `idleFor` 3301/3313 毫秒(正是配置的上界),耗时 22.1/21.9 秒对照 CI 的 17.5/20.9 秒,且所有输出断言仍然通过。CI 的触发条件本身未能在本地复现,因此该用例保留其断言并在组合中提供 `promptTailGraceMs`:它度量受控提示符路径而不是宿主机的投递时序,且在完全没有提示符标记时仍然失败。 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index cf43f07cb8..3253bad00b 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -3384,6 +3384,14 @@ export interface Config { * regain the foreground before `inferred_idle` settles; at least one `pollIntervalMs`. */ handoffGraceMs?: number + /** + * Extra wait beyond `idleSilenceMs` and `handoffGraceMs`, once a prompt marker was seen but + * its printable tail has not arrived, before `inferred_idle` settles. The marker is written + * by the shell's own prompt function and the tail by the same render, so a missing tail is a + * delivery delay on a contended host rather than an absent prompt. Zero keeps the bound at + * `idleSilenceMs + handoffGraceMs`. + */ + promptTailGraceMs?: number /** Absolute bound for one send and the complete pwsh startup sequence. */ timeoutMs?: number /** Grace before teardown escalates to `SIGKILL`. */ diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index e9e22b4c7f..0bae3875d6 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -3386,6 +3386,14 @@ export interface Config { * regain the foreground before `inferred_idle` settles; at least one `pollIntervalMs`. */ handoffGraceMs?: number + /** + * Extra wait beyond `idleSilenceMs` and `handoffGraceMs`, once a prompt marker was seen but + * its printable tail has not arrived, before `inferred_idle` settles. The marker is written + * by the shell's own prompt function and the tail by the same render, so a missing tail is a + * delivery delay on a contended host rather than an absent prompt. Zero keeps the bound at + * `idleSilenceMs + handoffGraceMs`. + */ + promptTailGraceMs?: number /** Absolute bound for one send and the complete pwsh startup sequence. */ timeoutMs?: number /** Grace before teardown escalates to `SIGKILL`. */ diff --git a/packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts b/packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts index 1b43d1efaa..088521fe5c 100644 --- a/packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts +++ b/packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts @@ -100,6 +100,12 @@ describe.skipIf(!hasPwsh)('persistent pwsh through a real cordis.yml Loader comp // send's wait reason, which pins the controlled-prompt fast path directly // instead of relying on how long silence would take to settle. ' handoffGraceMs: 300', + // The self-hosted Windows pool stalls the console renderer for seconds (issue 2487): the + // OSC marker reaches the session while the five-byte prompt tail that follows it does not + // arrive until the plain silence bound has passed, and every such send used to settle as + // inferred_idle. The tolerance keeps those sends on the controlled-prompt path this case + // pins, without letting a missing prompt (no marker at all) escape the silence tier. + ' promptTailGraceMs: 5000', ' scrollbackLines: 20000', // The first call pays the full pwsh cold-start latency (spawn + .NET + // PSReadLine + Defender) inside the tool deadline; a 60s bound on the diff --git a/packages/terminal/terminal-bash/README.i18n.yaml b/packages/terminal/terminal-bash/README.i18n.yaml index f908f43f13..9582708b9b 100644 --- a/packages/terminal/terminal-bash/README.i18n.yaml +++ b/packages/terminal/terminal-bash/README.i18n.yaml @@ -24,11 +24,11 @@ en: 71449ef1985b2f1b zh: 562e9b5ef73cd5e1 /deepseek-ai-dsh-terminal-bash/use-this-package/configuration: - en: 229375735e02e80a - zh: 347c617ae312643a + en: c5d0197950c2207a + zh: 0e7b8b08fd6e4b0e /deepseek-ai-dsh-terminal-bash/use-this-package/shell-dialects-and-readiness: - en: bab340c3347f1794 - zh: a4c32b651fea000d + en: 2cab01d85f524e3d + zh: 0d00b3e399a935b1 /deepseek-ai-dsh-terminal-bash/use-this-package/sandboxing-and-safe-operation: en: 39e0f0b429b024a7 zh: 440171193664d13b diff --git a/packages/terminal/terminal-bash/README.md b/packages/terminal/terminal-bash/README.md index 466a42f468..9e817678a6 100644 --- a/packages/terminal/terminal-bash/README.md +++ b/packages/terminal/terminal-bash/README.md @@ -56,12 +56,13 @@ Mount the terminal service, a subprocess provider, the sandbox and policy servic | `maxReadBytes` | `262144` | Maximum UTF-8 bytes returned by one read or settled send | | `timeoutMs` | `30000` | Absolute bound on one send wait | | `disposeGraceMs` | `3000` | Grace before teardown escalates to `SIGKILL` | +| `promptTailGraceMs` | `0` | Extra wait for a seen prompt marker's printable tail before `inferred_idle` settles | -The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-terminal-bash) is the exhaustive source for every field, including the readiness timings (`pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, `handoffGraceMs`), terminal size (`rows`, `cols`), and scrollback bounds (`scrollbackLines`, `scrollbackMaxBytes`). +The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-terminal-bash) is the exhaustive source for every field, including the readiness timings (`pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, `handoffGraceMs`, `promptTailGraceMs`), terminal size (`rows`, `cols`), and scrollback bounds (`scrollbackLines`, `scrollbackMaxBytes`). ### Shell dialects and readiness -Both dialects expose the same readiness contract, so consumers are dialect-agnostic. A send settles when the shell is ready again: after the controlled prompt is verified, after the foreground process group provably waits on stdin (Linux), after output silence (`inferred_idle`), or at the absolute `timeoutMs`. An `inferred_idle` or `timeout` result does not prove the foreground command exited. +Both dialects expose the same readiness contract, so consumers are dialect-agnostic. A send settles when the shell is ready again: after the controlled prompt is verified, after the foreground process group provably waits on stdin (Linux), after output silence (`inferred_idle`), or at the absolute `timeoutMs`. A prompt marker whose printable tail has not arrived yet holds the send on the exact path for `promptTailGraceMs` beyond `idleSilenceMs + handoffGraceMs`, because the marker and its tail are written by the same prompt render. An `inferred_idle` or `timeout` result does not prove the foreground command exited. ### Sandboxing and safe operation diff --git a/packages/terminal/terminal-bash/README.zh.md b/packages/terminal/terminal-bash/README.zh.md index 7ca41883f6..19067913d0 100644 --- a/packages/terminal/terminal-bash/README.zh.md +++ b/packages/terminal/terminal-bash/README.zh.md @@ -56,12 +56,13 @@ kind: "package-reference" | `maxReadBytes` | `262144` | 一次读取或一次结算发送返回的最大 UTF-8 字节数 | | `timeoutMs` | `30000` | 一次发送等待的绝对上限 | | `disposeGraceMs` | `3000` | 清理升级到 `SIGKILL` 前的宽限时间 | +| `promptTailGraceMs` | `0` | 已看到提示符标记后,等待其可打印尾部再按 `inferred_idle` 结算的额外时长 | -生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-terminal-bash)是每个字段的穷尽式真源,包括就绪计时(`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs`、`handoffGraceMs`)、终端尺寸(`rows`、`cols`)与 scrollback 上限(`scrollbackLines`、`scrollbackMaxBytes`)。 +生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-terminal-bash)是每个字段的穷尽式真源,包括就绪计时(`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs`、`handoffGraceMs`、`promptTailGraceMs`)、终端尺寸(`rows`、`cols`)与 scrollback 上限(`scrollbackLines`、`scrollbackMaxBytes`)。 ### shell 方言与就绪 -两种方言暴露相同的就绪约定,因此消费方与方言无关。当 shell 再次就绪时发送即结算:受控提示符被验证之后、前台进程组被证明在等待 stdin(Linux)之后、输出静默(`inferred_idle`)之后,或到达绝对 `timeoutMs`。`inferred_idle` 或 `timeout` 结果并不证明前台命令已退出。 +两种方言暴露相同的就绪约定,因此消费方与方言无关。当 shell 再次就绪时发送即结算:受控提示符被验证之后、前台进程组被证明在等待 stdin(Linux)之后、输出静默(`inferred_idle`)之后,或到达绝对 `timeoutMs`。若提示符标记已到达而其可打印尾部尚未到达,send 会在 `idleSilenceMs + handoffGraceMs` 之外继续等待 `promptTailGraceMs`,因为标记与尾部由同一次提示符渲染写出。`inferred_idle` 或 `timeout` 结果并不证明前台命令已退出。 ### 沙箱与安全运行 diff --git a/packages/terminal/terminal-bash/src/config.ts b/packages/terminal/terminal-bash/src/config.ts index 9a13bd9f90..beba58e22e 100644 --- a/packages/terminal/terminal-bash/src/config.ts +++ b/packages/terminal/terminal-bash/src/config.ts @@ -37,6 +37,14 @@ export interface Config { * regain the foreground before `inferred_idle` settles; at least one `pollIntervalMs`. */ handoffGraceMs?: number + /** + * Extra wait beyond `idleSilenceMs` and `handoffGraceMs`, once a prompt marker was seen but + * its printable tail has not arrived, before `inferred_idle` settles. The marker is written + * by the shell's own prompt function and the tail by the same render, so a missing tail is a + * delivery delay on a contended host rather than an absent prompt. Zero keeps the bound at + * `idleSilenceMs + handoffGraceMs`. + */ + promptTailGraceMs?: number /** Absolute bound for one send and the complete pwsh startup sequence. */ timeoutMs?: number /** Grace before teardown escalates to `SIGKILL`. */ @@ -95,12 +103,15 @@ export const Config: z = z.object({ exactProbeAfterMs: z.number().default(150), idleSilenceMs: z.number().default(3_000), handoffGraceMs: z.number().default(500), + promptTailGraceMs: z.number().default(0), timeoutMs: z.number().default(30_000), disposeGraceMs: z.number().default(3_000), }) /** - * Assert every effective numeric config field is a positive safe integer and bounds compose. + * Assert every effective numeric config field is a positive safe integer — except + * `promptTailGraceMs`, whose zero is the documented "no extension" value — and that bounds + * compose. * @param config - Schemastery-resolved plugin configuration. * @returns Narrows the input to the fully resolved configuration. */ @@ -109,10 +120,15 @@ export function validateConfig(config: Config): asserts config is ResolvedConfig if (resolved.backendType.length === 0) throw new Error('terminal-bash: backendType must be non-empty') if (resolved.shellPath.length === 0) throw new Error('terminal-bash: shellPath must be non-empty') for (const [name, value] of Object.entries(resolved)) { + if (name === 'promptTailGraceMs') continue if (typeof value === 'number' && (!Number.isSafeInteger(value) || value <= 0)) { throw new Error(`terminal-bash: ${name} must be a positive safe integer`) } } + if (typeof resolved.promptTailGraceMs === 'number' + && (!Number.isSafeInteger(resolved.promptTailGraceMs) || resolved.promptTailGraceMs < 0)) { + throw new Error('terminal-bash: promptTailGraceMs must be a non-negative safe integer') + } if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) { throw new Error('terminal-bash: maxReadBytes must not exceed scrollbackMaxBytes') } diff --git a/packages/terminal/terminal-bash/src/session.ts b/packages/terminal/terminal-bash/src/session.ts index 6bc9ee3f4a..f70197ea98 100644 --- a/packages/terminal/terminal-bash/src/session.ts +++ b/packages/terminal/terminal-bash/src/session.ts @@ -584,7 +584,13 @@ export class LocalPtySession implements TerminalBackendSession { // on waiting for shell ownership instead of letting a child marker suppress // readiness until the absolute timeout. const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0 - if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) { + // A seen marker whose printable tail has not arrived is the prompt function's own + // evidence that the shell reached its prompt: the tail is written by the same render, + // so its absence within the bound is a delivery delay rather than an absent prompt. + // The configured tolerance keeps the send on the exact path instead of charging it the + // silence tier; zero restores the plain `idleSilenceMs + handoffGraceMs` bound. + const tailGrace = this.promptSeen && !this.promptTextSeen ? this.config.promptTailGraceMs : 0 + if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace + tailGrace) { this.settleActive('inferred_idle') } } catch (error: unknown) { diff --git a/packages/terminal/terminal-bash/tests/config.spec.ts b/packages/terminal/terminal-bash/tests/config.spec.ts index 252a49c3d1..3c299c34f6 100644 --- a/packages/terminal/terminal-bash/tests/config.spec.ts +++ b/packages/terminal/terminal-bash/tests/config.spec.ts @@ -6,7 +6,7 @@ function config(overrides: Partial = {}): Config { return { backendType: 'shell', shellDialect: 'bash', shellPath: '/bin/bash', shellArgs: [], rows: 40, cols: 160, scrollbackLines: 100, scrollbackMaxBytes: 1024, maxReadBytes: 512, - pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 100, handoffGraceMs: 50, timeoutMs: 1000, + pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 100, handoffGraceMs: 50, promptTailGraceMs: 0, timeoutMs: 1000, disposeGraceMs: 100, ...overrides, } @@ -30,6 +30,13 @@ describe('terminal-bash config', () => { expect(() => { validateConfig(config({ handoffGraceMs: 10, pollIntervalMs: 10 })) }).not.toThrow() }) + it('accepts the prompt tail grace at zero and rejects negative or fractional values', () => { + expect(() => { validateConfig(config({ promptTailGraceMs: 0 })) }).not.toThrow() + expect(() => { validateConfig(config({ promptTailGraceMs: 2_000 })) }).not.toThrow() + expect(() => { validateConfig(config({ promptTailGraceMs: -1 })) }).toThrow('promptTailGraceMs must be a non-negative safe integer') + expect(() => { validateConfig(config({ promptTailGraceMs: 1.5 })) }).toThrow('promptTailGraceMs must be a non-negative safe integer') + }) + }) describe('terminal-bash dialect resolution', () => { diff --git a/packages/terminal/terminal-bash/tests/index.spec.ts b/packages/terminal/terminal-bash/tests/index.spec.ts index 16b7f9ffce..c733803db0 100644 --- a/packages/terminal/terminal-bash/tests/index.spec.ts +++ b/packages/terminal/terminal-bash/tests/index.spec.ts @@ -44,7 +44,7 @@ function config(): ResolvedConfig { return { backendType: 'shell', shellDialect: 'bash', shellPath: '/bin/bash', shellArgs: [], rows: 24, cols: 80, scrollbackLines: 10, scrollbackMaxBytes: 100, maxReadBytes: 50, - pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 50, handoffGraceMs: 10, timeoutMs: 100, + pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 50, handoffGraceMs: 10, promptTailGraceMs: 0, timeoutMs: 100, disposeGraceMs: 10, } } diff --git a/packages/terminal/terminal-bash/tests/session-buffer.spec.ts b/packages/terminal/terminal-bash/tests/session-buffer.spec.ts index 0c22181b3a..a9127ac650 100644 --- a/packages/terminal/terminal-bash/tests/session-buffer.spec.ts +++ b/packages/terminal/terminal-bash/tests/session-buffer.spec.ts @@ -44,7 +44,7 @@ function fixture(overrides: Partial = {}) { backendType: 'shell', shellDialect: 'bash', shellPath: '/bin/bash', shellArgs: [], rows: 24, cols: 80, scrollbackLines: 10_000, scrollbackMaxBytes: 4 * 1024 * 1024, maxReadBytes: 256 * 1024, pollIntervalMs: 60_000, exactProbeAfterMs: 60_000, idleSilenceMs: 60_000, - handoffGraceMs: 60_000, timeoutMs: 60_000, disposeGraceMs: 60_000, + handoffGraceMs: 60_000, promptTailGraceMs: 0, timeoutMs: 60_000, disposeGraceMs: 60_000, ...overrides, } const producer = new OutputProducer() diff --git a/packages/terminal/terminal-bash/tests/session.spec.ts b/packages/terminal/terminal-bash/tests/session.spec.ts index c8597bf5bd..05a8e78eb4 100644 --- a/packages/terminal/terminal-bash/tests/session.spec.ts +++ b/packages/terminal/terminal-bash/tests/session.spec.ts @@ -141,7 +141,7 @@ function config(overrides: Partial = {}): ResolvedConfig { return { backendType: 'shell', shellDialect: 'bash', shellPath: '/bin/bash', shellArgs: [], rows: 24, cols: 80, scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64, - pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 50, handoffGraceMs: 10, timeoutMs: 100, + pollIntervalMs: 10, exactProbeAfterMs: 20, idleSilenceMs: 50, handoffGraceMs: 10, promptTailGraceMs: 0, timeoutMs: 100, disposeGraceMs: 20, ...overrides, } @@ -530,6 +530,54 @@ describe('LocalPtySession readiness and output', () => { expect((await operation.done).waitReason).toBe('stdin_read') }) + it('keeps waiting for a seen prompt marker with a delayed tail up to promptTailGraceMs', async () => { + vi.useFakeTimers() + const terminal = new FakeTerminal() + const inspector = new FakeInspector() + const session = makeSession(terminal, inspector, config({ idleSilenceMs: 50, handoffGraceMs: 10, promptTailGraceMs: 200 })) + try { + await initialize(session, terminal) + + const operation = session.startSend({ text: 'slow-render', submit: true }) + await Promise.resolve() + await Promise.resolve() + let settled: string | undefined + void operation.done.then((result) => { settled = result.waitReason }) + + // The marker arrives; its printable tail is delayed by the host. The plain bound + // (`idleSilenceMs + handoffGraceMs`) passes without settling the silence tier. + terminal.emitData('\x1b]133;D;0\x07') + await vi.advanceTimersByTimeAsync(70) + expect(settled).toBeUndefined() + + // The tail lands inside the tolerance and the exact prompt path settles the send. + terminal.emitData('dsh> ') + await vi.advanceTimersByTimeAsync(20) + expect((await operation.done).waitReason).toBe('stdin_read') + } finally { + await session.close('prompt tail grace cleanup') + } + }, 5_000) + + it('charges the silence tier at the plain bound when promptTailGraceMs is zero', async () => { + vi.useFakeTimers() + const terminal = new FakeTerminal() + const inspector = new FakeInspector() + const session = makeSession(terminal, inspector, config({ idleSilenceMs: 50, handoffGraceMs: 10, promptTailGraceMs: 0 })) + try { + await initialize(session, terminal) + + const operation = session.startSend({ text: 'slow-render', submit: true }) + await Promise.resolve() + await Promise.resolve() + terminal.emitData('\x1b]133;D;0\x07') + await vi.advanceTimersByTimeAsync(70) + expect((await operation.done).waitReason).toBe('inferred_idle') + } finally { + await session.close('prompt tail grace cleanup') + } + }, 5_000) + it('captures prompt MOTD, writes submit explicitly, and settles exact stdin waits', async () => { vi.useFakeTimers() const terminal = new FakeTerminal()