@treeseed/dsh-chapters 0.2.3 → 0.2.5

package/docs/contract.md

@@ -604,7 +604,17 @@ and does not let a plugin do, with anchors:
   `{value.result.kind/text}`). New **wire events are NOT available to plugins**: the forwarded
   allowlist is app-owned ("the one home of this application's forwarded-Host-event allowlist",
   `packages/api/remotes/src/remote-events.ts:24`).
-- **Push transport is 0.2.x-only.** `appendPluginRecord(session, 'plugin:<name>', data)`
+  **Every execution is recorded** (measured, `packages/interaction/commands/src/index.ts:365-385`):
+  `command/run` + `command/done` lifecycle events, log-only (never model surface) but rendered as
+  history nodes by the web UI; `recordInput: false` (definition flag, `index.ts:71-75`) suppresses
+  only the `args` payload, NOT the node pair. There is no quiet-invocation mode — a polling client
+  on this wire writes visible history every pull, which is why the bar's cadence is a tested
+  decision (#193) and the push swap (#194) is the structural fix.
+- **Push transport is 0.2.1+ (measured 2026-10-30, #193 — this line said "0.2.x-only" and was
+  wrong):** `appendPluginRecord` has **zero occurrences** at tag `dsh-v0.2.0-rc.2`
+  (`packages/core/session/src/index.ts`) and is present at `dsh-v0.2.1-rc.2` (`:492`). The pinned
+  rig host (0.2.0-rc.2) therefore CANNOT serve the push swap; #194 gates on a host-pin bump plus
+  feature detection with pull fallback. `appendPluginRecord(session, 'plugin:<name>', data)`
   (`packages/core/session/src/index.ts:492`, grammar/types at `types.ts:525-543`, reader
   `pluginRecordOf` at `index.ts:508`): durable, append-only, "never enters the model-visible
   surface", retained by fork/resume, skipped by unknown readers. The `verify-plugin-record-callers`

package/lib/client.js

@@ -94,7 +94,7 @@ window.__ModuleLoader__.load({
 				case "goal": return {
 					...state,
 					goalPhase: ev.phase,
-					autorun: ev.phase === "complete" ? "disarmed" : state.autorun
+					autorun: ev.phase === "complete" || ev.phase === "blocked" ? "disarmed" : state.autorun
 				};
 			}
 			return state;
@@ -105,6 +105,23 @@ window.__ModuleLoader__.load({
 			if (s.status === "ready" || s.status === "failed") return "Recommended Next Step";
 			return null;
 		}
+		/**
+		* #193: the pull cadence, as a decision instead of an interval constant. Every pull is two recorded
+		* host lifecycle events (`command/run` + `command/done`) the UI renders as history nodes — cadence
+		* IS the litter, so it belongs in this module with a row for every arm. Active = the state can
+		* plausibly change on a short clock (generation in flight, an armed loop to fire, a turn running
+		* that will end into an offer). Quiet = stable; one pull a minute is plenty for a state that only
+		* changes at turn boundaries. Hidden-and-quiet = pull NOTHING (a background tab should write zero
+		* history); hidden-and-active still pulls, because walking away from a running loop is the point of
+		* autorun and pausing it silently would be the loop dying with nobody told.
+		*/
+		const ACTIVE_POLL_MS = 1e4;
+		const QUIET_POLL_MS = 6e4;
+		function pollSpacingFor(s) {
+			const active = s.status === "analyzing" || s.autorun === "armed" || s.running;
+			if (!active && s.hidden) return null;
+			return active ? ACTIVE_POLL_MS : QUIET_POLL_MS;
+		}
 		function barVisible(s) {
 			if (s.status === "off") return false;
 			if (s.status === "ready" && (s.text === null || s.text === "")) return false;
@@ -119,7 +136,7 @@ window.__ModuleLoader__.load({
 			if (s.goal !== null && s.goal.phase === "active" && s.goal.activation === "armed") return false;
 			if (s.autorun !== "armed") return false;
 			if (s.running) return false;
-			if (s.goalPhase === "complete") return false;
+			if (s.goalPhase === "complete" || s.goalPhase === "blocked") return false;
 			if (s.hiddenTurnSeq !== null && s.hiddenTurnSeq === s.turnSeq) return false;
 			return true;
 		}
@@ -310,9 +327,6 @@ window.__ModuleLoader__.load({
 		const PULL_TIMEOUT_MS = 15e3;
 		/** 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. */
-		/** Cadence of the keep-poll. A local RPC that answers in milliseconds; the cost is one command per
-		* interval, and it ends the moment the state is `off`. */
-		const POLL_SPACING_MS = 1e4;
 		function execWithTimeout(exec, line, ms) {
 			return new Promise((resolve, reject) => {
 				const timer = setTimeout(() => {
@@ -341,6 +355,7 @@ window.__ModuleLoader__.load({
 				alive.current = false;
 			}, []);
 			const [busy, setBusy] = (0, react.useState)(false);
+			const kick = (0, react.useRef)(void 0);
 			const answered = (0, react.useRef)(false);
 			const replyStatus = (0, react.useRef)("unknown");
 			const stateRef = (0, react.useRef)(initialBarState());
@@ -380,22 +395,43 @@ window.__ModuleLoader__.load({
 				pulled.current = true;
 				let timer;
 				const tick = async () => {
-					await refresh();
+					const spacing = pollSpacingFor({
+						status: replyStatus.current,
+						autorun: stateRef.current.autorun,
+						running: stateRef.current.running,
+						hidden: typeof document !== "undefined" && document.hidden === true
+					});
+					if (spacing !== null) await refresh();
 					if (replyStatus.current === "off") return;
 					timer = setTimeout(() => {
 						tick();
-					}, POLL_SPACING_MS);
+					}, spacing ?? 6e4);
+				};
+				kick.current = () => {
+					if (timer !== void 0) clearTimeout(timer);
+					tick();
+				};
+				const onVisible = () => {
+					if (typeof document !== "undefined" && !document.hidden) kick.current?.();
 				};
+				if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisible);
 				tick();
 				return () => {
 					if (timer !== void 0) clearTimeout(timer);
+					kick.current = void 0;
+					if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisible);
 				};
 			}, [refresh]);
+			const prevRunning = (0, react.useRef)(props.running ?? true);
 			(0, react.useEffect)(() => {
+				const next = props.running ?? true;
+				const prev = prevRunning.current;
+				prevRunning.current = next;
 				dispatch({
 					t: "running",
-					running: props.running ?? true
+					running: next
 				});
+				if (prev && !next) kick.current?.();
 			}, [props.running]);
 			const run = (0, react.useCallback)(() => {
 				if (state.text === null || state.text === "" || exec === void 0) return;