better-dsh 0.2.2-a → 0.2.2-c

package/lib/index.js

@@ -8319,7 +8319,7 @@ async function defaultSchemeWrite(scheme, path$1, content) {
 * write definition with args and exec passed through untouched.
 */
 function createWriteTool(deps) {
-	const { nativeWrite, postWrite, preWriteFormat } = deps;
+	const { nativeWrite, postWrite, preWriteFormat, sandbox } = deps;
 	const writeScheme = deps.writeScheme ?? defaultSchemeWrite;
 	return defineTool({
 		name: "write",
@@ -8334,7 +8334,8 @@ function createWriteTool(deps) {
 				type: "string",
 				required: true,
 				description: "Full new content (an empty string writes an empty file)."
-			}
+			},
+			...sandbox !== void 0 && sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {}
 		},
 		output: {
 			schema: {
@@ -9832,6 +9833,7 @@ function installAgentTools(rootCtx, agent, resolver) {
 	agent.ctx.effect(async () => {
 		const native = captureNativeTools(rootCtx, agent);
 		const disposers = [];
+		const hashlineSandbox = new FsSandboxController(rootCtx);
 		disposers.push(agent.ctx.tools.register(createReadTool({
 			resolver,
 			fs: rootCtx.fs,
@@ -9839,10 +9841,10 @@ function installAgentTools(rootCtx, agent, resolver) {
 		})));
 		disposers.push(agent.ctx.tools.register(createWriteTool({
 			nativeWrite: native.write,
+			sandbox: hashlineSandbox,
 			...buildLspWriteFeedback()
 		})));
 		const hashlineIo = ctxFsIO(rootCtx.fs, rootCtx);
-		const hashlineSandbox = new FsSandboxController(rootCtx);
 		disposers.push(registerEditTool(rootCtx, agent.ctx, hashlineIo, hashlineSandbox));
 		disposers.push(registerUndoTool(rootCtx, agent.ctx, hashlineIo, hashlineSandbox));
 		disposers.push(registerWriteHook(rootCtx, agent.ctx, hashlineIo));
@@ -10707,6 +10709,251 @@ function installFailover(ctx, config = defaultFailoverConfig) {
 	});
 }
 
+//#endregion
+//#region src/mobile/zoom-guard.ts
+/**
+* Whether a UA string + touch-capability pair is an iOS-class browser
+* (design D2, mirroring Discourse `capabilities.isIOS`): iPhone/iPod/iPad,
+* plus iPadOS 13+ desktop-Safari masquerade (`Macintosh` UA with a
+* multi-touch digitizer). Deliberately NOT `pointer:coarse` — Android Chrome
+* never focus-zooms and `maximum-scale` has historical side effects there,
+* so the gate is tightened to the iOS family. UA-shape drift degrades
+* benignly: a novel UA simply reads as non-iOS and no rewriting happens.
+*
+* @param ua - `navigator.userAgent`.
+* @param maxTouchPoints - `navigator.maxTouchPoints` (0 when absent).
+* @returns `true` for iOS-class browsers.
+*/
+function isIOSClassUA(ua, maxTouchPoints) {
+	return /iPhone|iPod|iPad/.test(ua) || /Macintosh/.test(ua) && maxTouchPoints > 1;
+}
+/**
+* Token-level merge of viewport directives into a viewport meta `content`
+* string (design D4): existing tokens keep their positions, a token whose key
+* (compared case-insensitively) is in `tokens` is REPLACED by the configured
+* key=value, and configured keys not present are APPENDED in insertion order.
+* Idempotent by construction — merging always re-derives from the input, so
+* repeated evaluation cannot accumulate duplicates.
+*
+*   mergeViewportTokens('width=device-width, initial-scale=1', T)
+*   → 'width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no'
+*   mergeViewportTokens('width=device-width, maximum-scale=5', T)
+*   → 'width=device-width, maximum-scale=1, user-scalable=no'   // same-key override, position kept
+*
+* @param content - the stock (or stock-equivalent) content string.
+* @param tokens - the directives to merge, keyed lowercase.
+* @returns the merged content string.
+*/
+function mergeViewportTokens(content, tokens) {
+	var out = [];
+	var seen = {};
+	var parts = content.split(",");
+	for (var i = 0; i < parts.length; i++) {
+		var part = parts[i];
+		var raw = (part === void 0 ? "" : part).replace(/^\s+|\s+$/g, "");
+		if (raw === "") continue;
+		var eq = raw.indexOf("=");
+		var key = eq < 0 ? raw : raw.slice(0, eq).replace(/^\s+|\s+$/g, "");
+		var hit = null;
+		for (var k in tokens) if (tokens.hasOwnProperty(k) && k.toLowerCase() === key.toLowerCase()) {
+			hit = k;
+			break;
+		}
+		if (hit === null) {
+			out[out.length] = raw;
+			continue;
+		}
+		out[out.length] = hit + "=" + tokens[hit];
+		seen[hit] = true;
+	}
+	for (var j in tokens) if (tokens.hasOwnProperty(j) && !seen[j]) out[out.length] = j + "=" + tokens[j];
+	return out.join(", ");
+}
+/**
+* The double gate (design D2/D3 + the `zoomGuard` config): rewrite applies
+* only on an iOS-class browser AND a narrow viewport AND a non-`off`
+* `zoomGuard`. An absent payload (or absent key) means the `'meta'` default —
+* the same default-on posture as the mobile leg itself — so only an explicit
+* `'off'` disarms the guard. Unknown non-`off` values read as `'meta'`
+* (schema validation makes them unreachable in production; benign here).
+*
+* @param config - the `__DASHR_MOBILE__` payload (only `zoomGuard` is read).
+* @param isIOS - {@link isIOSClassUA} verdict for this page load.
+* @param isNarrow - `matchMedia('(max-width: breakpoint-0.02px)')` verdict.
+* @returns `true` when the viewport rewrite should be applied.
+*/
+function shouldApplyZoomGuard(config, isIOS, isNarrow) {
+	if (!isIOS || !isNarrow) return false;
+	if (!config) return true;
+	return config.zoomGuard !== "off";
+}
+/**
+* Standalone display-mode verdict (design D4 of change
+* `2026-09-03-zoomguard-standalone-font-floor`): standalone PWAs HONOR
+* `user-scalable=no` (the real-device pinch regression that motivated the
+* display-mode split), so they must never enter the meta-rewrite path. Two
+* sources, strict-`true` OR: the `(display-mode: standalone)` media query
+* (primary) and legacy `navigator.standalone` (older iOS Safari exposes only
+* the latter). Anything else — `undefined` (engine without the source),
+* `false`, or truthy junk — reads as NOT standalone.
+*
+* @param mqMatchesStandalone - `matchMedia('(display-mode: standalone)').matches`.
+* @param navStandalone - `navigator.standalone === true`.
+* @returns `true` in standalone display mode (either source).
+*/
+function isStandaloneDisplay(mqMatchesStandalone, navStandalone) {
+	return mqMatchesStandalone === true || navStandalone === true;
+}
+/**
+* The 16px font floor stylesheet (design D3): iOS auto-zooms on focus into
+* ANY control whose computed font-size is below 16px, so in standalone mode
+* — where the meta rewrite is off the table (pinch must stay
+* engine-available) — the floor IS the suppression. Scoped by the same
+* breakpoint band the meta leg uses and derived the same way
+* (`breakpoint - 0.02`: 768 → 767.98, 900 → 899.98); `!important` beats the
+* 13/14px CSS module rules and the body inline var chain;
+* `[contenteditable="true"]` matches only the editable state (React
+* serializes `contentEditable={bool}` to the literal attribute value
+* "true"/"false").
+*
+* @param breakpointPx - the configured `mobile.breakpoint` (raw — this
+* function derives the `-0.02` band itself, do NOT pre-subtract).
+* @returns the complete stylesheet text.
+*/
+function buildFontFloorCss(breakpointPx) {
+	return "@media (max-width:" + (breakpointPx - .02) + "px){ input,textarea,select,[contenteditable=\"true\"]{ font-size:16px !important } }";
+}
+/**
+* Build the boot script's zoomGuard section: the five decision predicates
+* embedded via `toString()` plus the DOM state machine that applies them.
+* The machine implements design D3/D4 with one discovered refinement —
+*
+* **The standalone fork (2026-09-03, change
+* `2026-09-03-zoomguard-standalone-font-floor`).** Real-device datum:
+* standalone (Add to Home Screen) iOS HONORS `user-scalable=no`, so the
+* meta rewrite that is benign in-browser (pinch stays engine-controlled)
+* kills pinch in the PWA — the user's primary surface. The section
+* therefore forks right after the iOS gate, BEFORE any meta machinery: a
+* one-shot startup verdict (display-mode never flips mid-session) via the
+* `(display-mode: standalone)` MQ or legacy `navigator.standalone` (D4).
+* Standalone → inject the `ios-zoom-font-floor` style element into the
+* head (16px floor, media-query-scoped to the same breakpoint band, D3)
+* and RETURN — no provisional meta, no reconcile observer, no ladder
+* timer, no listeners, byte-identical stock meta (D1). The width dimension
+* lives inside the stylesheet's media query, so the injection itself is
+* NOT width-gated: a wide standalone load still gets the element; the rule
+* simply does not match above the breakpoint. Browser mode runs the v0.2.4
+* machinery unchanged.
+* **Why reconciliation exists.** The webserver splices head injections
+* immediately after the opening `<head>` tag, i.e. BEFORE the stock
+* `<meta name="viewport">` in upstream's `index.html`. At boot-script time
+* the stock meta is therefore NOT yet parsed, so the "meta missing"
+* branch is the NORMAL path on the served shell, not an edge case. A
+* provisional meta is created right away (the timing requirement: the
+* suppressive tokens are live before any application bundle can focus an
+* input), and a MutationObserver watches for the parser to insert the stock
+* meta; the moment it appears, the guard records the true stock content,
+* rewrites the STOCK meta (token merge, D4's actual semantics — restore
+* later writes these exact bytes back), and removes the provisional one —
+* leaving a single-meta document instead of relying on engines'
+* unspecified multi-meta merge behavior. Engines without MutationObserver
+* keep the provisional meta for the page's lifetime (degraded but still
+* suppressive); the observer is never started once the stock meta was
+* found synchronously.
+*
+* **Why the re-evaluation ladder exists (2026-09-03 rework, lead CDP
+* finding on the 4999 instance).** The boot script runs during head parsing,
+* BEFORE the engine applies the stock viewport meta — the layout viewport at
+* first evaluation is the pre-meta engine default (980px observed), so
+* `mq.matches` reads false on an initial narrow load, and the narrowing that
+* follows meta application does NOT reliably dispatch `resize` to the page
+* during load (headless Chrome: never). A ~10ms poll ladder therefore
+* re-evaluates until the guard IS applied, `document.readyState` reaches
+* `'complete'`, or ~2s elapse — the first layout always precedes deferred
+* scripts, so the ladder lands the guard before any application bundle can
+* focus an input. Steady-state ticks are idempotent no-ops; a wide load
+* idles to the readyState stop and leaves no timer behind (a pending tick
+* is also cancelled the moment the guard lands). MediaQuery `change` events
+* (with the legacy `addListener` fallback) form a second re-evaluation
+* channel alongside window `resize`.
+*
+* State machine (ES5, zero dependencies, synchronous first evaluation):
+* `meta` is the element under management (provisional or reconciled stock),
+* `stock` its recorded stock content, `mine` whether we created it,
+* `applied` the last applied gate verdict. `apply(on)` is idempotent per
+* state (no-op when the verdict is unchanged); merges always re-derive
+* from the recorded stock, never from the live content, so resize storms
+* cannot accumulate tokens. Non-iOS pages never wire any listener.
+*
+* Emitted only when the mobile payload exists and `zoomGuard !== 'off'`.
+*
+* @returns the inline section text (truthy `var` declarations + IIFE).
+*/
+function buildZoomGuardSection() {
+	return [
+		`var ZI=${isIOSClassUA.toString()};`,
+		`var ZM=${mergeViewportTokens.toString()};`,
+		`var ZS=${shouldApplyZoomGuard.toString()};`,
+		`var ZD=${isStandaloneDisplay.toString()};`,
+		`var ZF=${buildFontFloorCss.toString()};`,
+		"(function(){",
+		"var m=window.__DASHR_MOBILE__;",
+		"var ios=ZI(navigator.userAgent,(navigator.maxTouchPoints||0));",
+		"if(!ios)return;",
+		"var bpx=(m&&typeof m.breakpoint==='number'&&m.breakpoint>0)?m.breakpoint:768;",
+		"var bp=bpx-0.02;",
+		"var sa=ZD((window.matchMedia&&window.matchMedia('(display-mode: standalone)').matches),(navigator.standalone===true));",
+		"if(sa){var f=document.createElement('style');f.setAttribute('id','ios-zoom-font-floor');f.setAttribute('data-plugin','better-dsh');f.setAttribute('data-plugin-css','better-dsh/zoom-font-floor');f.textContent=ZF(bpx);headEl().appendChild(f);return}",
+		"var mq=(typeof window.matchMedia==='function')?window.matchMedia('(max-width:'+bp+'px)'):null;",
+		"var T={'maximum-scale':'1','user-scalable':'no'};",
+		"var meta=null,stock=null,mine=false,applied=false,obs=null,lad=null,lN=0;",
+		"function findStock(){var s=document.getElementsByTagName('meta');for(var i=0;i<s.length;i++){var e=s[i];if(e!==meta&&(e.getAttribute('name')||'').toLowerCase()==='viewport')return e}return null}",
+		"function headEl(){return document.head||document.getElementsByTagName('head')[0]||document.documentElement}",
+		"function stopWatch(){if(obs){obs.disconnect();obs=null}}",
+		"function stopLadder(){if(lad){clearTimeout(lad);lad=null}}",
+		"function dropMine(){if(meta&&mine){if(meta.parentNode)meta.parentNode.removeChild(meta);meta=null;mine=false}}",
+		"function apply(on){",
+		"if(on===applied)return;",
+		"applied=on;",
+		"if(on)stopLadder();",
+		"if(on){",
+		"var el=findStock();",
+		"if(el){meta=el;mine=false;stock=el.getAttribute('content')||''}",
+		"else if(!meta){meta=document.createElement('meta');meta.setAttribute('name','viewport');mine=true;stock='';headEl().appendChild(meta)}",
+		"meta.setAttribute('content',ZM(stock,T));",
+		"if(mine&&typeof MutationObserver==='function'&&!obs){obs=new MutationObserver(check);obs.observe(document.documentElement,{childList:true,subtree:true})}",
+		"}else{",
+		"stopWatch();",
+		"if(!meta)return;",
+		"if(mine)dropMine();",
+		"else meta.setAttribute('content',stock);",
+		"}",
+		"}",
+		"function check(){",
+		"var el=findStock();",
+		"if(!el)return;",
+		"stopWatch();",
+		"stock=el.getAttribute('content')||'';",
+		"if(applied){dropMine();meta=el;mine=false;meta.setAttribute('content',ZM(stock,T))}",
+		"else{dropMine();meta=null;stock=null}",
+		"}",
+		"function re(){apply(ZS(m,true,mq?mq.matches:false))}",
+		"function tick(){",
+		"lad=null;",
+		"re();",
+		"if(applied)return;",
+		"lN++;",
+		"if(document.readyState==='complete'||lN>=200)return;",
+		"lad=setTimeout(tick,10);",
+		"}",
+		"re();",
+		"window.addEventListener('resize',re);",
+		"if(mq&&mq.addEventListener)mq.addEventListener('change',re);else if(mq&&mq.addListener)mq.addListener(re);",
+		"if(!applied&&typeof setTimeout==='function')lad=setTimeout(tick,10);",
+		"})()"
+	].join("");
+}
+
 //#endregion
 //#region src/web-trust.ts
 /**
@@ -10752,12 +10999,16 @@ function buildBootScript(config) {
 		...mobile?.dominanceRatio !== void 0 ? { dominanceRatio: mobile.dominanceRatio } : {},
 		...mobile?.leftEdgeBandPx !== void 0 ? { leftEdgeBandPx: mobile.leftEdgeBandPx } : {},
 		...mobile?.rightZoneRatio !== void 0 ? { rightZoneRatio: mobile.rightZoneRatio } : {},
-		...mobile?.swipeVelocityPxPerMs !== void 0 ? { swipeVelocityPxPerMs: mobile.swipeVelocityPxPerMs } : {}
+		...mobile?.swipeVelocityPxPerMs !== void 0 ? { swipeVelocityPxPerMs: mobile.swipeVelocityPxPerMs } : {},
+		...mobile?.zoomGuard !== void 0 ? { zoomGuard: mobile.zoomGuard } : {}
 	} : void 0;
 	if (authorities.length === 0 && mobilePayload === void 0) return void 0;
 	const parts = ["(function(){try{"];
 	if (authorities.length > 0) parts.push("if(!window.__DSH_TRANSPORT__){", `var h=location.hostname,a=${JSON.stringify(authorities)};`, "for(var i=0;i<a.length;i++)if(a[i]===h){window.__DSH_TRANSPORT__={ownsHost:true};break}", "}");
-	if (mobilePayload !== void 0) parts.push(`window.__DASHR_MOBILE__=${JSON.stringify(mobilePayload)};`);
+	if (mobilePayload !== void 0) {
+		parts.push(`window.__DASHR_MOBILE__=${JSON.stringify(mobilePayload)};`);
+		if (mobile?.zoomGuard !== "off") parts.push(buildZoomGuardSection());
+	}
 	parts.push("}catch(e){}})();");
 	return parts.join("");
 }
@@ -10802,7 +11053,8 @@ const MOBILE_CONFIG = z.object({
 	dominanceRatio: z.number().min(1).default(1.3),
 	leftEdgeBandPx: z.natural().min(8).default(120),
 	rightZoneRatio: z.number().min(.05).max(.9).default(.25),
-	swipeVelocityPxPerMs: z.number().min(0).default(.15)
+	swipeVelocityPxPerMs: z.number().min(0).default(.15),
+	zoomGuard: z.union(["meta", "off"]).default("meta")
 });
 /** Runtime schema. */
 const Config = z.intersect([DashrRuntime.Config, z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-dsh",
-  "version": "0.2.2-a",
+  "version": "0.2.2-c",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/docs/REPL-/345/267/245/345/205/267/350/260/203/347/224/250-/346/210/252/346/226/255/350/257/212/346/226/255.md

@@ -1,110 +0,0 @@
-# REPL 工具调用截断诊断（v0.2.1b 实测中发现，2026-09-01）
-
-## 结论先行
-
-**任何从 REPL（`eval` cell）内部发起的工具调用（`tool.<name>(...)`）都会让 dsh web daemon 进程崩溃并自动重启；会话日志在 `tool/code-dispatch-start` 处撕裂，恢复时 repair 机制合成「interrupted-tool-result」，模型看到的即「工具调用被截断、结果未知」。** 4 次探针 4 次复现，与 journald 守护进程崩溃记录逐条对应。
-
-这不是 REPL 同步/异步的问题，也不是 subagent 特有问题——是 dashr 子分派桥接层的结构性缺陷 + 部署运行态注册表视图缺 symbol 的直接原因叠加。
-
-## 一、复现矩阵（第一人称）
-
-| # | cell 内容 | 结果 |
-|---|---|---|
-| 1 | `await tool.subagent({… run_in_background: false })` | 截断（daemon 崩溃 17:39:17） |
-| 2 | `await tool.subagent({… run_in_background: true })` | 截断（daemon 崩溃 17:41:15） |
-| 3 | `await tool.bash({… run_in_background: true })` | 截断（daemon 崩溃 17:57:05） |
-| 4 | `await tool.read({path: "dashr/package.json"})` | 截断（daemon 崩溃 18:02:27） |
-
-对照：纯 Python cell（`dir(tool)`、顶层 `return` 判错、`await asyncio.sleep(0)`）全部正常。**凡含 `tool.*` RPC 的 cell 必崩，与工具、与 background 与否无关。**
-
-## 二、截断面定位（三层证据）
-
-### 1. 会话日志（`~/.dsh/sessions/…/session.jsonl.zstd`）
-4 次截断的共同指纹：`tool/call (eval)` → `tool/code-dispatch-start`（**已持久化**）→ 日志撕裂（无 `tool/code-dispatch`、无 `step/end`/`turn/end`）→ 重载时 `packages/core/session/src/repair.ts` 的 `interruptedTurnClosers` 合成 `interrupted-tool-result-<callId>-<seq>`（`TOOL_OUTCOME_UNKNOWN`）。会话内 **0 条 error 事件**——错误根本没走到会话层。
-
-### 2. 守护进程日志（`journalctl --user -u dsh.service`）——铁证
-```
-Sep 01 17:39:17 pnpm[414449]: dsh: fatal load failure: TypeError: Cannot read properties of undefined (reading 'prepare')
-    at Object.start (…/better-dsh/lib/index.js:11281:41)
-    at <anonymous> (…/lib/index.js:11191:21)
-    at drive (…/lib/index.js:11207:7)
-    at outcome (…/lib/index.js:11310:6)
-    at new Promise (<anonymous>)
-    at toolFunctions.<computed> (…/lib/index.js:11320:72)
-    at Proxy.dispatchHostRequest (…/lib/index.js:2180:21)
-Sep 01 17:39:19 systemd: dsh.service: Main process exited, code=exited, status=1/FAILURE
-Sep 01 17:39:23 systemd: dsh.service: Scheduled restart job, restart counter is at 1.
-```
-17:39:17 / 17:41:15 / 17:57:05 / 18:02:27 四次崩溃，栈完全一致。`scheduler.prepare` 中 `scheduler` 为 `undefined`——即 `registry[TOOL_RUNTIME_SCHEDULER]` 在部署运行态取不到值。
-
-### 3. 源码链（`dashr/src/index.ts`）
-- kernel 侧：`tool.<name>(...)` → `binding.call` RPC（`src/bootstrap.ts` `_dashr_callable`）。
-- host 侧：`dispatchHostRequest`（`src/runtime.ts:545`）→ `await fn(args)`（`src/index.ts` `binding()`）。
-- `binding()` 内部（`src/index.ts:666`）：`const scheduler = registry[TOOL_RUNTIME_SCHEDULER]` → 单驱动道 `drive()`（`src/index.ts:591-621`）→ `start()` 内 `await scheduler.prepare(input)`（`src/index.ts:712`）。
-- **结构性缺陷**：`drive()` 的 async IIFE 是 `try { … } finally { … }`，**没有 catch**；调用处是 `void drive()`。任何 `start()`/`commit()` 抛错（如 `scheduler.prepare` TypeError）都会变成 **unhandled rejection**——binding promise 既不 resolve 也不 reject，cell 永久挂起，错误外泄给进程。
-**完整链条**：cell 工具调用 → dispatch 启动（`code-dispatch-start` 已入日志）→ `registry[TOOL_RUNTIME_SCHEDULER]` 为 undefined → `scheduler.prepare` TypeError → driver 无 catch → unhandled rejection → `installFailLoud` 判定 fatal → daemon exit(1) → systemd 重启 → 会话重载 repair 合成「interrupted-tool-result」→ 模型收到截断消息。**截断面：binding 桥 → registry symbol 查询 → driver 的未处理拒绝。**
-
-## 三、命名澄清：REPL dispatch log 与 code-dispatch 是两个不同层（重要）
-
-容易混淆，先分清：
-
-| 名字 | 层级 | 是谁 | 本次 change 是否改名 |
-|---|---|---|---|
-| `tool/code-dispatch-start` / `tool/code-dispatch` | **会话持久日志事件**（durable log，`agent.session.append`） | dashr `src/index.ts:689,712`；harness `known-event-types.ts:63-64` 注册 | **否**——v0.1.x 就有，历史遗留名 |
-| `dashr/repl-dispatch-log` | **waterfall 扩展点**（内容整形监听事件） | dashr 自注册（`src/index.ts:458`） | **是**——v0.2.1 从上游 `tools/code-dispatch-log`/`tools/ptc-dispatch-log` 改名为「自己的 REPL dispatch log」 |
-| `tools/ptc-dispatch-log` | waterfall（上游 PTC 用） | harness `src/ptc.ts:282` + spill policy 监听（`spill-policy/src/index.ts:217`） | dashr 已不再 emit（仅注释提及） |
-
-**结论**：
-- 「自己的 REPL dispatch log」`dashr/repl-dispatch-log` **在代码里存在且自注册**——目标形态已就位。它之所以「没被触发」，是因为崩溃发生在它之前的 `scheduler.prepare`（它在 settle 之后才跑）——**是崩溃的结果，不是原因**。
-- 会话日志里我用作定位证据的 `tool/code-dispatch-start` 是**持久日志事件名**，与 waterfall 改名无关，只是「撕裂点之前最后一条已写入事件」的定位标记。
-- 改名引入了一个**真实但非崩溃的副作用**：harness 的 spill policy 仍监听上游 `tools/ptc-dispatch-log`，dashr 不再 emit → 溢出限幅（oversized 结果的 preview+locator 替换）对 eval 子调用日志**静默失效**。**已补（2026-09-01 晚，见六）**：dashr `shapeDispatchLog` 跑完 `dashr/repl-dispatch-log` 后，再把同一 dispatch（载荷结构与上游 `PtcDispatchLog` 完全一致）喂进 `tools/ptc-dispatch-log` 载体，spill 臂恢复生效。改动在 `dashr/src/index.ts`，lib 已重建（`f0febba7…`），**部署位同步 + daemon 重启待用户执行**。
-
-## 四、为什么 `registry[TOOL_RUNTIME_SCHEDULER]` 是 undefined（直接原因）
-
-
-- 已排除：dsh-tools 双副本 symbol 不一致（实测插件与 daemon 均解析到同一 realpath `/home/u1/workspaces/dsh-alpha/packages/core/tools`，symbol 严格相等）；dashr 分派代码改动（266d232/06e516a/HEAD 逐字节一致）；dsh-tools alpha.1 vs alpha.3 差异（仅 import 整理/ToolCallId brand 等外观差异）。
-- 关键观察：`classify()` 调用的 `registry.executionMode(input)` **正常**（`code-dispatch-start` 已写入日志，证明 `start()` 之前的分派逻辑跑通），而 `registry[TOOL_RUNTIME_SCHEDULER]` **取不到**。`executionMode` 是 ToolRuntime 类方法、`TOOL_RUNTIME_SCHEDULER` 是类实例 symbol 字段——即部署运行态 `runtimeCtx.tools` 返回的**不是原生 ToolRuntime 实例**，而是一个有方法、缺实例 symbol 字段的服务视图（cordis 作用域服务解析 / plugin tree 挂载路径差异）。
-- 测试为什么全绿：dashr 测试组合（`test/helpers.ts`）把 `ctx.tools` 解析到**根作用域的原生 ToolRuntime 实例**，symbol 在位；生产组合经 harness plugin tree / scope 层解析，拿到的是视图。
-- **何时坏的（重要修正）**：v0.1.8 实测报告（2026-08-24）实证 DASHR 自己的 `eval` 桥当时**正常工作**——同 cell 并发 `tool.read` + `tool.bash` 完成。2026-08-28 会话用的是 harness 自带 PTC `run_cell`（`tools.bash`，复数命名空间 = PTC SDK 形态；该 PTC 核心经 `@deepseek-ai/dsh-code-runtime-python` 执行 **Python**，非 TS），不能代表 dashr 桥状态。**崩溃由 2026-09-01 的 harness alpha（0.1.2-alpha.1）升级引入**——升级后 plugin tree 里 `runtimeCtx.tools` 变成缺实例 symbol 字段的服务视图；dashr v0.2.1 的 dispatch-log 改名不是崩溃原因。
-
-## 五、REPL 同步/异步问题的回答（顺带闭环）
-
-- 模型层：`eval` 是同步工具调用，模型等 cell 结果——这是设计使然，与缺陷无关。
-- cell 内：`tool.<name>(...)` 是 kernel→host 的 `binding.call` RPC，被 cell `await`；host 经与原生调用同一 registry 分派器执行。`run_in_background: true` 的工具实现**快速返回 id**（subagent `{kind:'continuable', subagentId}`、bash 返回 job id），background 语义本应保留、子任务与 cell 结束无关。
-- 但**当前运行时该路径整体坏掉**：任何子分派在 `scheduler.prepare` 即 TypeError，与 background 无关——所以「在 REPL 里 background 是否异步」目前是伪问题，路径不通；修好后 background 语义会按上述设计成立。
-
-## 六、修复方向（分层）
-
-1. **dashr 立即修（阻断 daemon 崩溃）**：`drive()` 加 catch / `start()`、`commit()` 失败必须 settle binding promise 为错误结果——cell 内工具调用失败应变成可见的 `ToolCallError`，**绝不允许以 unhandled rejection 外泄杀 daemon**。这是把「任何分派错误」放大成「整个运行时崩溃」的放大器，无论直接原因是什么都必须先修。
-2. **dashr 防御**：`registry[TOOL_RUNTIME_SCHEDULER]` 为 undefined 时抛带上下文的 loud 错误（cell 可见），而不是裸 `undefined.prepare` TypeError。
-3. **根因定位（harness 接线）**：在活体 daemon 上探针确认 plugin tree 中 `runtimeCtx.tools` 的实际对象（cordis 作用域服务视图 / 第二个 tools 实例），修正挂载使插件拿到原生 ToolRuntime（symbol 在位）。这一步需要 daemon 侧可写环境（本会话 bwrap 沙箱只读宿主，无法直接探查活体）。
-4. **测试补强（部分完成）**：已加「`tools/ptc-dispatch-log` 载体回喂」回归用例（`test/bridge.spec.ts`，全量 396 绿）。仍缺「生产形态」挂载测试——按 harness 的 plugin-tree/scope 方式挂载插件，断言 `ctx.tools[TOOL_RUNTIME_SCHEDULER]` 已定义 + 一个真实工具 RPC 从 cell 完成；防止此环境差异回归。
-5. **回归核验基线**：修复后重跑本文档第一节的 4 探针矩阵（4/4 应全部返回结果而非截断），并观察 `journalctl --user -u dsh.service` 无新崩溃。
-
-## 附：证据文件
-- 会话日志：`~/.dsh/sessions/--home-u1-workspaces-dashr--/session-ad9ac311-3400-4304-b501-e7303da850df/session.jsonl.zstd`
-- 守护进程日志：`journalctl --user -u dsh.service`（17:39:17 / 17:41:15 / 17:57:05 / 18:02:27 四条 fatal load failure）
-- 对照工作会话：`06ac8b2c-fb2e-458f-80d6-a0d28e50f193`（2026-08-28，9 对完整 code-dispatch，PTC run_cell 路径）
-
----
-
-## 七、v0.2.1c 修复执行记录（2026-09-01，change v0-2-1c-repl-tool-crash-fix）
-
-### 六.1 + 六.2 已实现（dashr 侧）
-
-- `drive()` async IIFE 补 `catch`：lane 级 backstop——任何逃逸 start()/commit() 自身包裹的错误（或 classify() 抛错）settle 所有 queued-but-unsettled 分派为可见错误、清空队列、复位 exclusive、记 warn，**绝不外泄 unhandled rejection**。
-- `PendingDispatch` 新增 `fail(error)`：把 binding promise settle 为 `{ isError: true, message }`（经 `settleError` → `settle`，kernel 转 `ToolCallError`）。
-- `start()` / `commit()` 各自 try/catch：prepare 失败、dispatch body rejection、finalize/finish 失败都 settle 自己的 binding，不再向 lane 抛。
-- `binding()` 内 `registry[TOOL_RUNTIME_SCHEDULER]` 判空：undefined 时抛带上下文的 loud 错误（点名 symbol、指向 harness 挂载接线），替代裸 `undefined.prepare` TypeError。
-- 回归测试 3 个（`test/bridge.spec.ts`，全量 399 绿含 3 新）：view 缺 symbol → cell 收到含 `TOOL_RUNTIME_SCHEDULER` 的 loud 错误；`scheduler.prepare` 抛错 → binding settle 为可见错误；classify 抛错 → lane backstop settle 且进程存活。
-
-### 六.3 根因探针（本轮结论，待活体 daemon 复核）
-
-- **根因已锁定并更正（2026-09-02 活体探针 + 受控实验；推翻本节 2026-09-01 的 shadow 分支推断）**：真实根因是**部署拓扑 dual-copy**——崩溃期（2026-09-01 17:39–18:02）部署位插件嵌套 `node_modules/@deepseek-ai/*` 的 17 条 symlink（已退役 dev 接线）指向 dsh-alpha 源码树，插件 import 的 `TOOL_RUNTIME_SCHEDULER` 来自 alpha 副本的 dsh-tools 模块实例；daemon 的 `ToolRuntime` 实例由 host vendored 副本构建，其 symbol 字段以 host 副本 symbol 为键。两 symbol 为不同 `Symbol()` 实例：跨副本读实例字段 → `undefined`（`executionMode` 等字符串键方法不受影响、照常工作——症状逐字吻合）。
-- 证据链（2026-09-02）：① 活体 4 探针（`tool.bash` fg/bg、`tool.read`、`tool.subagent` bg:false/bg:true）经 `eval` cell 路径 4/4 真实结果——现行生产形态 symbol 在位；② 部署位 `require.resolve('@deepseek-ai/dsh-tools')` = `/home/u1/.local/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-tools/lib/index.js`（host vendored，③→④ 层）；③ 受控实验：host 与 z_dsh-alpha 两副本 `TOOL_RUNTIME_SCHEDULER` 严格不等，host 键实例经 alpha symbol 读 → `undefined`、经 host symbol 读 → object；④ 时间线闭环：改名 `dsh-alpha → z_dsh-alpha`（2026-09-01 22:29）→ symlink 悬空 → 2026-09-02 清理删除 → daemon 重启 → 自愈。
-- shadow 分支理论为何被否：它与症状吻合但从未被活体证实，且无法解释「拓扑清理 + 重启后自愈」；dual-copy 机制同时解释故障与恢复。v0.2.1c 报告引「symbol 严格相等」的排除测量与崩溃期拓扑矛盾（疑测同一副本两次或取于改名后），以直接证据为准。
-- cordis traceable proxy 本身无嫌疑（symbol 转发分支在位；现行活体 plain read 即返回带 symbol 原生实例）。
-- dashr 侧交付边界：六.1+六.2（不崩溃 + loud 错误）继续有效；dual-copy 已由部署拓扑收敛消除（部署纪律：插件 `node_modules/@deepseek-ai/` 只留 `schemastery`+`cosmokit`）；v0.2.1d 给 guard 错误附 dsh-tools 解析路径实现事件自诊断。
-### 六.4 生产形态挂载测试（说明）
-
-- 三个回归用例以「缺 symbol 视图」「prepare 抛错」「classify 抛错」三种形态驱动 `createRunCellTool`，覆盖六.1+六.2 全部防御面；测试组合（根作用域原生实例）本就 symbol 在位，断言 `runtimeCtx.tools[TOOL_RUNTIME_SCHEDULER]` 定义的用例属于测试组合自身形态（根挂载原生实例），无法复现生产 realm 差异——该差异须在活体 daemon 上复核（六.5）。

package/docs/adr/0001-bridge-tool-layer-not-service-layer.md

@@ -1,14 +0,0 @@
-# Bridge the tool layer, not the service layer
-
-DASHR's `rlm()` family dispatches upstream delegation tools through the tool registry (nested sub-dispatch), not `ctx.subagents` service methods. The tool layer carries the deployment's enforcement surface — approval pipeline, sandbox policy, per-instance config (maxDepth, backgroundMode, persona) — that a direct service call would silently bypass. The cost: per-call model selection is impossible, because the tool schema exposes no `model` parameter; `rlm(model=...)` from 0.1.4 is dropped, and `subagentModel` degrades to a static `agentOptions.model` in the preset patch.
-
-## Considered Options
-
-- **Service layer direct** (0.1.4's approach): `ctx.subagents.start()` with a hand-built request. Full control over request fields (including `agentOptions.model` and `maxDepth`), but every policy the tool instance would have applied must be re-implemented or lost.
-- **Tool layer nested dispatch** (chosen): `rlm("spawn")` executes the registry's `subagent` tool with a parent token. Upstream policy is inherited wholesale; the schema boundary is the tool's own contract.
-
-## Consequences
-
-- `rlm(mode, prompt, *, label, run_in_background)` — no `model` kwarg. Parent-model inheritance is the default; a different child model requires a preset patch, not a call argument.
-- Depth enforcement comes from the tool instance's `maxDepth` config, patched to 10 in the preset (see `dev/kernel-refactoring/V0.1.5-development-plan.md` Q22/Q23).
-- The upstream delegation tools (`subagent`, `subagent_fork`, `interrupt_agent`) must stay registered and executable even though the model never sees their names — which is why masking is presentation-only (ADR-0002).

package/docs/adr/0002-masking-is-presentation-only.md

@@ -1,15 +0,0 @@
-# Masking is presentation-only
-
-Hiding exactly two upstream A2A tool names (`send_message` — the parent→child downlink — and `report` — the child→parent uplink) from the model is done by excluding them from the generated Tool Catalog text and from the kernel binding names — nothing else. The two tools stay registered, executable, and dispatchable; the single `send_message` bridge dispatches them internally. Every OTHER upstream delegation tool (`subagent`, `subagent_fork`, `list_agents`, `interrupt_agent`, `workflow`, `ralph`) is exposed directly as a native `tool.*` member — no re-wrapping (v0.1.9).
-
-## Considered Options
-
-- **`restrict()` at runtime**: hides names in the registry's model-facing view, but validates against the live view at call time — ordering hazards against late tool registration can fail the whole preset mount.
-- **`disabled: true` include patches**: physically unregisters the tool, which also removes the bridge's dispatch target. Masking must not break the bridge.
-- **Presentation-only exclusion** (chosen): the registry is never touched. The model's surface (wire schema collapse to `eval`, Tool Catalog text, kernel bindings) is entirely DASHR-generated, so exclusion happens at the two points DASHR owns.
-
-## Consequences
-
-- The masked tools remain in the registry and are reachable via nested sub-dispatch with a parent token, which passes the model-direct guard.
-- **Field-verified (v0.1.8d, `both` presentation mode)**: reachable by MODEL-DIRECT native call too — no parent token needed. A probe calling the masked `skill({"name":…})` through the API function-call surface executed in full. Cause: the mask registers no visibility filter, so the name stays in `view(scope).visible`, and `resolveExecution` collapses model-direct calls only under `code` mode. The mask is an ADVERTISING cut, not an enforcement point; the hard gate is the REPL binding allowlist (`unknown binding`). If a deployment ever needs true model-direct rejection, the mechanisms are a visibility-layer `restrict()` (rejected here for ordering hazards) or a `code`-mode collapse — both are deployment-level decisions, not mask-level ones.
-- Zero upstream mutation means zero interference with host-plane modules that enumerate or interact with the delegation tools.