Skip to content

docs(dsh): document the ungated probe-healthy/pinned-recover landings (#1788) - #1792

Merged
ranxianglei merged 1 commit into
2026-10-01_dsh-stale-landing-guardfrom
2026-10-01_dsh-landing-boundary-note
Oct 1, 2026
Merged

ranxianglei merged 1 commit into
2026-10-01_dsh-stale-landing-guardfrom
2026-10-01_dsh-landing-boundary-note

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #1788

Stacked on #1787 — based on 2026-10-01_dsh-stale-landing-guard (#1787's head). The boundary notes reference landingOwnsRegister, which #1787 introduces; rebase onto master once #1787 merges.

What

#1787's stale-landing guard (landingOwnsRegister) covers the four slow-path write sites in verifyAttachAndRecover but leaves the two early landings unguarded:

  • probe-healthy short-circuit (src/agent/dsh-native.ts:285-286)
  • pinned-target-recovered write (src/agent/dsh-native.ts:293-294)

This takes resolution (b) from the issue: document the boundary + pin the safe direction with a test. No behavior change.

Why (b) over (a)

Naively extending the predicate to these sites desyncs the unconditional return home / return back from register.base in the blocked case (return says X, base stays elsewhere) — a return-contract violation needing a follow-up semantic change. For a low-severity, narrow-trigger, self-correcting residual, documenting the convergence argument is the safer call (#1039 "document the boundary" discipline). If you'd rather have (a), the delta is guard + return-consistency at both sites.

Convergence argument (now documented in-source)

  • With routed evidence present, home/back === state.routedOrigin — the same origin onRoutedOriginObserved rebinds to → converges, no clobber.
  • maybeRetry's respawn() joins the same single-flight mid-flight → no independent writer moves base.
  • Narrow residual (exotic multi-lifecycle interleave where base holds a different LIVE origin set up outside routed evidence) → transient tool-binding to that other live proxy, self-correcting on the next request's routed-evidence rebind. No data loss / deadlock.

Test

New regression test pins the safe direction: startup attach with routed evidence to a LIVE origin distinct from a LIVE preset asserts the probe-healthy landing binds to the routed origin (never the preset, never a spawn). Distinct from the #1365 suite (dead targets). Verified to fail when the routed preference is removed (teeth check).

Pre-flight

  • typecheck ✓
  • full test suite: 3472 tests, 0 fail ✓
  • build ✓

…#1788)

#1787's stale-landing guard (landingOwnsRegister) covers the four slow-path
write sites in verifyAttachAndRecover but leaves the two early landings
ungated: the probe-healthy short-circuit and the pinned-target-recovered
write. This documents WHY they are intentionally exempt and pins the safe
direction with a regression test.

Boundary notes (src/agent/dsh-native.ts):
- the probe-healthy and pinned-recovered landings converge rather than
  clobber: with routed evidence present, home/back === state.routedOrigin —
  the same origin onRoutedOriginObserved rebinds to — and maybeRetry's
  respawn() joins the same single-flight, so no independent writer moves base
  mid-flight.
- narrow residual (exotic multi-lifecycle interleave where base holds a
  different LIVE origin set up outside routed evidence) -> tools bind briefly
  to that other live proxy; the next request's routed evidence rebinds back.
  Transient, self-correcting, no data loss or deadlock.
- records why NOT to force the predicate here: the unconditional `return home`
  would then desync from register.base (return says X, base stays elsewhere).

Test (tests/dsh-native.test.ts): startup attach with routed evidence to a LIVE
origin distinct from a LIVE preset asserts the probe-healthy landing binds to
the routed origin, never the preset, never a spawn. Distinct from the #1365
suite (dead targets); verified to fail when the routed preference is removed.

Non-behavioral: comments + additive test only. Stacked on #1787.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

PR review complete — pulled the head (7b6f2001, stacked on #1787's 8665088d), traced every claim in the boundary notes against source, and reproduced the full pre-flight locally. No blocking findings; nothing to fix.

Verification performed

  • Diff: exactly 2 files, +68/−0 — boundary notes at the two ungated sites (src/agent/dsh-native.ts:285-297, :306-309) + one new regression test (tests/dsh-native.test.ts). Zero logic lines touched; single linear commit; clean.
  • Notes are accurate — traced each claim: home = state.routedOrigin ?? attachOrigin (:279); ungated write followed by unconditional return home (:298-300); pinned is by construction the routed-evidence origin (:302) and back = waitForProxyVersion(pinned) (:310); landingOwnsRegister = base === undefined || base === staleOrigin (:394-396) gating the slow-path sites (:318/:342/:352); onRoutedOriginObserved rebinds base to the observed routed origin behind a liveness check (:651-661). Convergence argument holds — and is slightly stronger than stated: when base already holds a live origin, maybeRetry takes the registerTools path (:452) and never touches base at all; only the base-less branch respawns, joining the same single-flight (:640-641 → :439-442).
  • (a) correctly rejected: guarding the write while keeping return home desyncs return value from register.base in the blocked case (verified against :298-300); done-right (a) changes return semantics → must-stay-human territory per §7.4. (b) matches the resolution envelope dsh-native: landing-ownership contract leaves the probe-healthy / pinned-recovery write sites unguarded (residual, low severity) #1788 itself proposed, and the prior analysis on dsh-native: landing-ownership contract leaves the probe-healthy / pinned-recovery write sites unguarded (residual, low severity) #1788 floor 3 reached the same recommendation. If you'd rather have (a), the delta is spelled out in the PR body.
  • Test has teeth: I ran it against a mutation (home = attachOrigin, routed preference removed) → fails exactly as designed (PANEL-PRESET: falls back to the live preset instead of the routed origin), then reverted clean. On the unmutated head: dsh-native.test.ts 42/42 pass. The test's distinguishing move over the bug: dsh-native — attach 目标瞬时不可达 → 回退 spawn 第二实例:routed baseURL 下工具/模型通道必然脑裂(工具 404 → preflight 502 → 会话不可自愈) #1365 suite is sound — both origins LIVE makes "honoured routed" vs "fell back to preset" observable.
  • Pre-flight reproduced at head: typecheck ✓ · build ✓ · full suite 3472 tests / 0 fail / 19 skipped (matches the PR's claim exactly). CI on the head sha: 5/5 workflow runs green (e2e pi/opencode/codex/dsh lanes + hermetic local registry); mergeable_state clean.

回归审查 (existing behaviors touched): none exist beyond "comments don't change runtime behavior", which holds trivially for a comments+additive-test diff. High-risk pattern sweep (semantic drift, threshold/timing/output-format change, fail-fast→swallow): negative. Test isolation: hooks reset in finally, mock proxies on dynamic ports like its siblings — no cross-file interference (full suite green).


结构化七问

  1. 是什么问题: fix(dsh): stale verifyAttachAndRecover landings must never clobber the self-healed register (#1783) #1787 的 stale-landing guard(landingOwnsRegister)只覆盖了 verifyAttachAndRecover 的四个慢路径写点,probe-healthy 短路(:298-300)和 pinned-recovered(:310-311)两个早期 landing 无守卫——一个低危、窄触发、可自愈的残留 clobber 风险。
  2. 什么原因导致的: 历史覆盖不对称——两个早期写点早于 fix(dsh): stale verifyAttachAndRecover landings must never clobber the self-healed register (#1783) #1787 的守卫机制存在,fix(dsh): stale verifyAttachAndRecover landings must never clobber the self-healed register (#1783) #1787 使不对称显形而非引入它。实质分析:有 routed evidence 时写入值与 onRoutedOriginObserved 的重绑目标相同(收敛而非覆盖),且飞行期内无独立写者能动 base,故今日安全。
  3. 怎么修复的: 取 dsh-native: landing-ownership contract leaves the probe-healthy / pinned-recovery write sites unguarded (residual, low severity) #1788 的方案 (b)——源码内边界注释记录收敛论证 + 明确警告"不要强加谓词"(否则无条件 return home 与 register.base 失步)+ 一个钉住安全方向的回归测试(双活 origin 下 routed evidence 压过 live preset、不 spawn)。零行为变更。
  4. 是否有回归问题: 无回归。审过的既有行为:probe-healthy 短路、pinned-recovery、三个慢路径守卫点、maybeRetry 自愈、onRoutedOriginObserved 重绑——全部未触碰(纯注释);高危模式逐项过,均阴性。
  5. 是否破坏缓存: 不涉及——未触碰任何 cache/retry/游标/去重逻辑。
  6. 是否改了设计方向: 不涉及——明确维持现状语义,并把 (a) 的取舍理由写进文档,属于"在正确层留边界记录"([bug] 插件透传会剥掉工具调用参数里的 render tag(arguments 流挂了 tag-echo 过滤器) #1039 纪律)。
  7. 是否引入了新的配置: 无新 env/config/默认值。

收工判定: 内容面可合——但它是 stack:需等 #1787 先合入 master,再按 PR 描述 rebase 到 master(让注释里引用的 landingOwnsRegister 在 master 上可解析),rebase 后 CI 重跑绿即可合。reviewer 侧无待办。

@ranxianglei
ranxianglei merged commit ea8adf1 into 2026-10-01_dsh-stale-landing-guard Oct 1, 2026
5 checks passed
@ranxianglei
ranxianglei deleted the 2026-10-01_dsh-landing-boundary-note branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant