@treeseed/dsh-chapters 0.2.7 → 0.2.9

package/docs/contract.md

@@ -706,6 +706,46 @@ version supplies, so Autorun reported itself unavailable on a host that exposes
 `{ captureInsertion, insertText, setDraft, addAttachments, removeAttachment, pruneAttachments, submit }`, and
 the composer-write limitation in #126 is measured against that same kit.
 
+**The running signal has seats, and the scalar is only one of them (measured 2026-10-31, #194).**
+`SessionSnapshot.running: boolean` (`packages/api/session-controller/src/client/contract/snapshot.ts:69-73`)
+arrives through the dock's standard prop `useSession` — a `MaybeSnapshotSelectorHook<SessionSnapshot>`
+(`useSession((s) => s.running)`), the same seat `ui-session` documents in `SessionStandardProps`.
+Some builds ALSO hand a scalar `running` prop. The shipped dock declared both hook channels
+(`useSessionStatus?`, `useSession?`) and consumed only the scalar — so on a hook-only host the #193
+idle edge never fired and the cadence silently degraded to the conservative 10s-active fallback
+(`props.running ?? true`). Resolution order, locked here: scalar `running` → `useSession((s) =>
+s.running)` → unknown (conservative true, legacy cadence). Conditional invocation of an optional
+hook prop is deliberate: the prop face is fixed per host build, so hook order is stable across
+renders within any one deployment, which is the invariant React actually keeps.
+
+**Push transport (interface lock, #194 — probe-verified on host 0.2.1-rc.5, `spikes/push-probe/FINDINGS.md`).**
+Where the host has `appendPluginRecord` (0.2.1+; absent from 0.2.0-rc.2 — grep-verified on both tags),
+the bar's state rides a plugin record and a projection, and the steady state costs ZERO command runs:
+
+- Record type: `plugin:dsh-chapters/prompt`. Payload = the bar's durable facts, versioned:
+  `{ v: 1, status, text, turnSeq, error, intent, goalRevision, autorun, at }`.
+- Append sites: every durable row write — the runner's `analyzing`/`ready`/`failed`/quiet-`off`
+  transitions (it holds the live session) and the bar-access mutations (`setAutorun`, `setOff`,
+  `setOn`, `runNow`'s consumption), which gain an optional live-session parameter for the purpose.
+- The function comes ONLY from the host's own module instance — `createRequire(process.argv[1])
+  → resolve('@deepseek-ai/dsh-session') → await import(resolved)`. The plugin's OWN copy at the
+  IDENTICAL version throws `Receiver must be an instance of class Session` against a host session
+  (measured), and a bare import from a `link:` install resolves by realpath into the source tree —
+  on a dev machine, into a DIFFERENT host checkout than the running server. No plugin dependency is
+  declared for it; detection is `typeof appendPluginRecord === 'function'`, one try behind try/catch,
+  and any failure marks push unavailable for the process.
+- Projection: key `chaptersPrompt`, registered ONLY when the writer resolved — registration is the
+  feature signal. `apply` folds records last-wins; `wire.view` passes the payload through.
+- Client: the dock reads the standard prop `useProjection('chaptersPrompt')`. A live value renders
+  through the SAME reducer (one fold path); `undefined` ⇒ the #203/#208 pull schedule stands,
+  unchanged — the fallback is the floor. In push mode the only pulls are the bar's own actions and
+  ONE staleness-confirm per idle edge, scheduled at +20s and cancelled when a fresher record arrives
+  (the runner writes `analyzing` within moments of turn/end, so a healthy push cancels every confirm):
+  a silently dead push degrades to one pull per turn, never to a frozen bar.
+- Records are `ignorable: true` with an unknown `plugin:` type — skipped by readers, rendered by
+  nothing; the projection value travels the host's own push channel. Verbs, state block, and the
+  pull schedule below are unchanged and remain the contract for pre-0.2.1 hosts.
+
 **Verbs (interface lock, #113).** `/chapters-prompt` accepts `model …|clear`, `off`, `on`, `state`, `autorun on|off`,
 and **`run`** — submit the offer currently on screen as a **human-authored user turn**, through the same follow-up
 path autorun uses (`agent.followup(suggestPromptMessage(…))`). Run goes through the command plane rather than the

package/lib/client.js

@@ -5,7 +5,73 @@ window.__ModuleLoader__.load({
 		var exports = module.exports;
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react = require("react");
-		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+		// src/client/tooltip.ts
+		/**
+		* The host's Tooltip seat, resolved OPTIONALLY (#194-compat — measured on 0.2.1-rc.5, not guessed):
+		*
+		* `@deepseek-ai/dsh-client-ui-primitives` exists in the 0.2.0-rc.2 host tree and is ABSENT from the
+		* entire 0.2.1-rc.5 install tree — no successor package exports `Tooltip`. Our bundle's static
+		* import becomes a LAZY require in the built CJS: the bundle loads and components run, but the
+		* first render that touches `Tooltip` throws, and React's error boundary swallows the subtree
+		* silently. Measured symptoms on 0.2.1: door registration fully healthy (inject returned a
+		* disposer; the factory ran; both register effects are functions) yet the assistant-actions region
+		* renders ZERO entries, and the dock renders no row — because both wrap their buttons in Tooltip.
+		*
+		* The fix keeps one resolution point and one fallback (#59 — never per-component try/catch):
+		* probe the module once; when it is absent, buttons carry the platform's own `title` tooltip, so
+		* hover text survives on every host and the fancy tooltip survives where it exists.
+		*/
+		/**
+		* The tooltip recipe, field for field the goal bar's own (GoalBar.tsx:101-142: `portal`,
+		* `side="bottom"`, `delayMs={500}`) — the shipped occupant of the same dock strip, whose tooltips
+		* are NOT covered by the composer. `portal` is the load-bearing one: it renders the popup at
+		* document level instead of inside our dock's stacking context, which is exactly the maintainer's
+		* report (#210: "the hoverover tooltips are covered by the main chat input container"). Our old
+		* compile-time types rejected portal/delayMs at the overload; the runtime host always accepted
+		* them, and since the seat is typed by us, the recipe is pinned by a row instead of by luck.
+		*/
+		function tooltipPropsFor(label) {
+			return {
+				label,
+				side: "bottom",
+				portal: true,
+				delayMs: 500
+			};
+		}
+		let resolved;
+		function resolveTooltip() {
+			if (resolved !== void 0) return resolved;
+			resolved = null;
+			try {
+				if (typeof require === "function") {
+					const T = require("@deepseek-ai/dsh-client-ui-primitives")?.Tooltip;
+					if (typeof T === "function" || typeof T === "object") resolved = T;
+				}
+			} catch {
+				resolved = null;
+			}
+			return resolved;
+		}
+		/** Wrap in the host Tooltip when it exists; otherwise return the child (which must carry `title`). */
+		function withTooltip(label, child) {
+			const T = resolveTooltip();
+			return T !== null ? (0, react.createElement)(T, {
+				...tooltipPropsFor(label),
+				children: child
+			}) : child;
+		}
+		/** The native-tooltip attribute, present ONLY when the host seat is absent — no double tooltips. */
+		function nativeTitle(label) {
+			return resolveTooltip() === null ? { title: label } : {};
+		}
+		// src/prompt-keys.ts
+		/**
+		* Identifiers shared by BOTH planes of the push transport (#194). One module, one spelling: the
+		* server registers the projection under this key and the client reads `useProjection(key)` — two
+		* literals in two planes would be exactly the drift #59 forbids. No node imports (the client
+		* compiles this), no DOM (the server imports this).
+		*/
+		const PROMPT_PROJECTION_KEY = "chaptersPrompt";
 		// src/client/prompt-bar.ts
 		function initialBarState(autorun = "disarmed") {
 			return {
@@ -136,6 +202,7 @@ window.__ModuleLoader__.load({
 		*/
 		function mountPullDecision(c) {
 			if (!c.hasCache) return true;
+			if (c.status === "off") return false;
 			if (c.autorun === "armed" || c.status === "analyzing") return true;
 			return c.ageMs > QUIET_POLL_MS;
 		}
@@ -250,6 +317,81 @@ window.__ModuleLoader__.load({
 				return deriveRunning(s.status ?? s.state ?? s.phase);
 			}
 		}
+		/**
+		* #208: the plane-wide relevance fact, read from the `state` block's own model line. `model: unset`
+		* means the feature does not exist on this plane — one discovery reply carrying it silences EVERY
+		* dock on the page (the pull transport cannot do better than one discovery; the push transport
+		* (#194) removes even that). An unrecognised block is false, never a guess.
+		*/
+		function parseModelAbsent(text) {
+			return /^\s*model:\s*unset\b/m.test(text);
+		}
+		/**
+		* A pushed payload becomes the SAME events the pull path dispatches — one fold, one reducer, no
+		* second implementation to drift (#59). Null when the payload is not ours or not trustworthy: an
+		* unrecognised push is ignored, never guessed at, and the pull schedule underneath keeps running
+		* until a payload this function accepts actually arrives.
+		*/
+		function pushEventsOf(payload) {
+			if (payload === null || payload === void 0 || typeof payload !== "object") return null;
+			const p = payload;
+			if (p.v !== 1 || typeof p.status !== "string") return null;
+			const status = p.status;
+			if (status !== "off" && status !== "idle" && status !== "analyzing" && status !== "ready" && status !== "failed") return null;
+			return {
+				polled: {
+					t: "polled",
+					status,
+					...status === "ready" ? {
+						text: typeof p.text === "string" ? p.text : "",
+						turnSeq: p.turnSeq ?? null,
+						intent: p.intent ?? "worker-step"
+					} : {},
+					...status === "failed" ? { error: p.error ?? "the suggestion call failed" } : {}
+				},
+				autorun: {
+					t: "autorun",
+					on: p.autorun === "armed"
+				}
+			};
+		}
+		/**
+		* The running signal's resolution order (scalar prop → `useSession` snapshot via `deriveRunning` →
+		* unknown) lives in the dock as `props.running ?? deriveRunning(sessionSnapshot)` — ONE expression,
+		* pinned by a source-scan row, folded by the deriveRunning rows that already cover every shape.
+		* A second pure helper for the same decision would be exactly the drift #59 forbids; the draft of
+		* #194 shipped one and this comment is its headstone.
+		*/
+		/** The staleness-confirm's one question: did a push arrive after the edge that scheduled it? */
+		function pushIsFresher(lastPushAt, edgeAt) {
+			return lastPushAt !== null && lastPushAt > edgeAt;
+		}
+		/**
+		* #218: a DEAD-PUSH HEARTBEAT, not a staleness confirm — 20s fired mid-turn before the turn's
+		* record could exist (turns outlast 20s), which was confirm spam wearing a safety hat. 5 minutes:
+		* during normal work a record arrives every turn and the push effect retires the pending timer, so
+		* a healthy push NEVER fires it; only a push silent for a whole 5 minutes pulls once — a frozen
+		* bar is the failure this bounds, and it is worth one node every 5 minutes, not one every 20
+		* seconds.
+		* within moments (the runner writes it BEFORE calling the model). If no push arrived this long
+		* after the edge, the push is presumed dead and ONE confirm pull runs — a silently dead push
+		* degrades to one pull per turn, never to a frozen bar.
+		*/
+		const PUSH_CONFIRM_GRACE_MS = 3e5;
+		/**
+		* #211 — the edge kick's delay, measured on the maintainer's host the hard way: some hosts publish
+		* `running` at STEP granularity (it flickers at every tool call and thinking block), and an
+		* immediate kick per falling edge was a rendered `chapters-prompt` node per tool call — all waste,
+		* because the server row changes ONLY at turn boundaries. So: a falling edge schedules its pull
+		* after the debounce, a rising edge cancels it (step flicker coalesces to zero pulls), and the rate
+		* floor bounds even a host that holds `running` low through long tool calls. A real turn end — a
+		* falling edge with no rising edge after it — pulls exactly once.
+		*/
+		const EDGE_DEBOUNCE_MS = 2e3;
+		const EDGE_FLOOR_MS = 15e3;
+		function edgeKickDelayMs(msSinceLastPull) {
+			return Math.max(EDGE_DEBOUNCE_MS, EDGE_FLOOR_MS - msSinceLastPull);
+		}
 		// src/client/prompt-dock.ts
 		/**
 		* The Suggested Next Step dock row (#113) — thin by design.
@@ -273,7 +415,7 @@ window.__ModuleLoader__.load({
 		* @module dsh-chapters/src/client/prompt-dock
 		*/
 		const CSS$1 = [
-			".dsh-chapters_promptDock{box-sizing:border-box;width:calc(100% - 4 * var(--dsh-composer-dock-inset));max-width:calc(var(--dsh-composer-card-max-width) - 4 * var(--dsh-composer-dock-inset));margin:0 auto}",
+			".dsh-chapters_promptDock{box-sizing:border-box;width:calc(100% - 2 * var(--dsh-composer-side-clearance) - 4 * var(--dsh-composer-dock-inset));max-width:calc(var(--dsh-composer-card-max-width) - 4 * var(--dsh-composer-dock-inset));margin:0 auto}",
 			".dsh-chapters_promptBar{isolation:isolate;box-sizing:border-box;width:100%;border-radius:var(--dsw-radius-md);height:36px;box-shadow:var(--dsw-elevation-panel);border:0;align-items:center;gap:10px;padding:4px 5px 4px 12px;display:flex;position:relative}",
 			".dsh-chapters_promptBar::before{z-index:-1;border-radius:inherit;background:var(--dsw-specific-menu);backdrop-filter:var(--dsw-menu-backdrop-filter);content:\"\";pointer-events:none;position:absolute;inset:0}",
 			".dsh-chapters_promptExpanded::before{align-items:flex-start;position:absolute;inset:0}",
@@ -326,14 +468,10 @@ window.__ModuleLoader__.load({
 				className: "dsh-chapters_promptBtn",
 				"aria-label": props.label,
 				...props.disabled === true ? { disabled: true } : {},
-				...props.title !== void 0 ? { title: props.title } : {},
+				...props.title !== void 0 ? { title: props.title } : nativeTitle(props.label),
 				onClick: props.onClick
 			}, props.glyph);
-			return (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.Tooltip, {
-				label: props.label,
-				side: "bottom",
-				children: button
-			});
+			return withTooltip(props.label, button);
 		};
 		/** Run is allowed whenever there is an offer; AUTORUN is what the intent and the goal gate. Keeping the
 		* human's own button enabled is deliberate — the point of the protocol is to route a goal edit to a keystroke,
@@ -354,6 +492,13 @@ window.__ModuleLoader__.load({
 		* answers in milliseconds when the session is attachable, and the failure it guards against is a hang. */
 		const PULL_TIMEOUT_MS = 15e3;
 		const stateCache = /* @__PURE__ */ new Map();
+		/**
+		* #208: set by the first reply reporting the plane-wide `model: unset` — the feature does not
+		* exist here, so NO dock on this page pulls again for anything: not mounts, not idle edges, not
+		* timers, not visibility. One discovery per page load is the pull transport's floor; a page reload
+		* is the only revival, and the enabling commands say so.
+		*/
+		let featureAbsent = false;
 		/** Retry ceiling for the FIRST pull only, in attempts and spacing. A mount-time race must not be able to
 		* starve the bar forever, and a real `off` answer stops the loop on the first reply either way. */
 		function execWithTimeout(exec, line, ms) {
@@ -372,11 +517,19 @@ window.__ModuleLoader__.load({
 		}
 		function PromptDock(props) {
 			const { sessionId, inputActions, exec } = props;
+			const sessionSnapshot = (props.useSession ?? (() => void 0))((snapshot) => snapshot);
+			const running = props.running ?? deriveRunning(sessionSnapshot);
+			const pushed = (props.useProjection ?? (() => void 0))(PROMPT_PROJECTION_KEY);
 			const [state, dispatch] = (0, react.useReducer)(promptBarReducer, initialBarState(), (s) => {
+				const pushEvs = pushEventsOf(pushed);
+				if (pushEvs !== null) return {
+					...promptBarReducer(promptBarReducer(s, pushEvs.polled), pushEvs.autorun),
+					running: running ?? true
+				};
 				const c = sessionId !== void 0 ? stateCache.get(sessionId) : void 0;
 				return {
 					...c !== void 0 ? stateFromCache(c.ev, c.autorun) : s,
-					running: props.running ?? true
+					running: running ?? true
 				};
 			});
 			const pulling = (0, react.useRef)(false);
@@ -388,6 +541,10 @@ window.__ModuleLoader__.load({
 			}, []);
 			const [busy, setBusy] = (0, react.useState)(false);
 			const kick = (0, react.useRef)(void 0);
+			const lastPullAt = (0, react.useRef)(null);
+			const edgeTimer = (0, react.useRef)(void 0);
+			const pushLiveRef = (0, react.useRef)(false);
+			const lastPushAt = (0, react.useRef)(null);
 			const answered = (0, react.useRef)(false);
 			const replyStatus = (0, react.useRef)("unknown");
 			const stateRef = (0, react.useRef)(initialBarState());
@@ -401,6 +558,7 @@ window.__ModuleLoader__.load({
 			const refresh = (0, react.useCallback)(async () => {
 				if (exec === void 0 || pulling.current) return;
 				pulling.current = true;
+				lastPullAt.current = Date.now();
 				try {
 					const text = await execWithTimeout(exec, BAR_STATE_COMMAND, PULL_TIMEOUT_MS);
 					try {
@@ -417,6 +575,7 @@ window.__ModuleLoader__.load({
 						t: "autorun",
 						on: autorun === "armed"
 					});
+					if (parseModelAbsent(text)) featureAbsent = true;
 					if (ev !== null && sessionId !== void 0) stateCache.set(sessionId, {
 						ev,
 						autorun: autorun === "armed" || autorun === "disarmed" ? autorun : null,
@@ -428,6 +587,18 @@ window.__ModuleLoader__.load({
 					pulling.current = false;
 				}
 			}, [exec]);
+			(0, react.useEffect)(() => {
+				const evs = pushEventsOf(pushed);
+				if (evs === null) return;
+				pushLiveRef.current = true;
+				lastPushAt.current = Date.now();
+				dispatch(evs.polled);
+				dispatch(evs.autorun);
+				if (edgeTimer.current !== void 0) {
+					clearTimeout(edgeTimer.current);
+					edgeTimer.current = void 0;
+				}
+			}, [pushed]);
 			(0, react.useEffect)(() => {
 				ensureCss();
 				if (pulled.current) return;
@@ -451,6 +622,8 @@ window.__ModuleLoader__.load({
 					});
 				};
 				const tick = async (opts) => {
+					if (pushLiveRef.current && opts?.force !== true) return;
+					if (featureAbsent) return;
 					if (effectiveStatus() === "off") {
 						if (!(opts?.mount === true && duePull())) return;
 					}
@@ -473,21 +646,40 @@ window.__ModuleLoader__.load({
 				tick({ mount: true });
 				return () => {
 					if (timer !== void 0) clearTimeout(timer);
+					if (edgeTimer.current !== void 0) {
+						clearTimeout(edgeTimer.current);
+						edgeTimer.current = void 0;
+					}
 					kick.current = void 0;
 					if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisible);
 				};
 			}, [refresh]);
-			const prevRunning = (0, react.useRef)(props.running ?? true);
+			const prevRunning = (0, react.useRef)(running ?? true);
 			(0, react.useEffect)(() => {
-				const next = props.running ?? true;
+				const next = running ?? true;
 				const prev = prevRunning.current;
 				prevRunning.current = next;
 				dispatch({
 					t: "running",
 					running: next
 				});
-				if (prev && !next) kick.current?.();
-			}, [props.running]);
+				if (prev && !next) {
+					if (edgeTimer.current !== void 0) clearTimeout(edgeTimer.current);
+					const since = lastPullAt.current === null ? Number.MAX_SAFE_INTEGER : Date.now() - lastPullAt.current;
+					const delay = pushLiveRef.current ? Math.max(PUSH_CONFIRM_GRACE_MS, edgeKickDelayMs(since)) : edgeKickDelayMs(since);
+					const edgeAt = Date.now();
+					edgeTimer.current = setTimeout(() => {
+						edgeTimer.current = void 0;
+						if (pushLiveRef.current && pushIsFresher(lastPushAt.current, edgeAt)) return;
+						kick.current?.();
+					}, delay);
+				} else if (!prev && next) {
+					if (edgeTimer.current !== void 0) {
+						clearTimeout(edgeTimer.current);
+						edgeTimer.current = void 0;
+					}
+				}
+			}, [running]);
 			const run = (0, react.useCallback)(() => {
 				if (state.text === null || state.text === "" || exec === void 0) return;
 				setBusy(true);
@@ -515,8 +707,7 @@ window.__ModuleLoader__.load({
 				if (!shouldAutoFire(state)) return;
 				run();
 			}, [state, run]);
-			const sessionSnapshot = (props.useSession ?? (() => void 0))((snapshot) => snapshot);
-			const autorunDisabled = (props.running ?? deriveRunning(sessionSnapshot)) === void 0;
+			const autorunDisabled = running === void 0;
 			if (sessionId === void 0 || !barVisible(state)) return null;
 			const populate = () => {
 				console.info(`[client:prompt] populate expanded=${String(state.expanded)} hasInsertText=${String(typeof inputActions?.insertText)} hasSetDraft=${String(typeof inputActions?.setDraft)} textLen=${String(state.text?.length ?? -1)}`);
@@ -600,7 +791,7 @@ window.__ModuleLoader__.load({
 							t: "autorun",
 							on: arm
 						});
-						await refresh();
+						if (!pushLiveRef.current) await refresh();
 					})();
 				}
 			}), (0, react.createElement)(Action, {
@@ -995,6 +1186,7 @@ window.__ModuleLoader__.load({
 				const button = (0, react.createElement)("button", {
 					type: "button",
 					"aria-label": door.label,
+					...nativeTitle(door.label),
 					disabled: busy,
 					onClick,
 					className: "dsh-chapters_forkAction"
@@ -1009,11 +1201,7 @@ window.__ModuleLoader__.load({
 					display: "inline-flex",
 					alignItems: "center",
 					gap: "4px"
-				} }, (0, react.createElement)(_deepseek_ai_dsh_client_ui_primitives.Tooltip, {
-					label: door.label,
-					side: "bottom",
-					children: button
-				}), note !== null ? (0, react.createElement)("span", { className: "dsh-chapters_forkNote" }, note) : null);
+				} }, withTooltip(door.label, button), note !== null ? (0, react.createElement)("span", { className: "dsh-chapters_forkNote" }, note) : null);
 			};
 		}
 		function apply(ctx) {
@@ -1052,12 +1240,18 @@ window.__ModuleLoader__.load({
 				}, { ...uiWorkspace !== void 0 ? { navigator: uiWorkspace } : {} }),
 				component: makeDoorAction(door)
 			}));
-			slots.inject("conversation.chat.assistant-actions", () => rows.map(({ door, run, component }) => slots.register({
-				name: "conversation.chat.assistant-actions",
-				id: door.id,
-				order: door.order,
-				inject: (sessionId) => ({ run: () => run(sessionId) })
-			}, component)));
+			console.info(`[client:chapters] injecting ${String(rows.length)} assistant-actions door(s)`);
+			const disposeDoors = slots.inject("conversation.chat.assistant-actions", () => {
+				const effects = rows.map(({ door, run, component }) => slots.register({
+					name: "conversation.chat.assistant-actions",
+					id: door.id,
+					label: door.label,
+					inject: (sessionId) => ({ run: () => run(sessionId) })
+				}, component));
+				console.info(`[client:chapters] door factory ran: ${String(effects.length)} register effect(s), types: ${effects.map((e) => typeof e).join(",")}`);
+				return effects;
+			});
+			console.info(`[client:chapters] assistant-actions inject returned ${typeof disposeDoors}`);
 			slots.inject("conversation.input.dock", () => slots.register({
 				name: "conversation.input.dock",
 				id: "chapters-prompt",