weir-harness 1.1.6 → 1.2.0

package/lib/client.settings-page.js

@@ -53,33 +53,43 @@ window.__ModuleLoader__.load({
 		const CLASSIFIER_JEV = Object.freeze({ key: "intentGateClassifier", equals: "jev" });
 		const WINDOWS_ONLY = Object.freeze({ env: "platform", in: Object.freeze(["win32"]) });
 		const ROBASH_WINDOWS = Object.freeze({ all: Object.freeze([enabledWhen("robashEnabled"), WINDOWS_ONLY]) });
-		// The GROUPS field table. Every node: { field?, kind, values?, display?,
-		// when?, parent?, folded?, slot? }. kind: boolean | enum | number | text |
-		// custom. An enum node may set `display: "select"` to render a compact
-		// native dropdown instead of the segmented control (long option labels
-		// squeeze the row label). `custom` nodes carry a render `slot` identifier
-		// and share
-		// parent/when with plain rows; a custom node with a `field` is
-		// text-backed at the form layer. `folded` fields stay in the form but
-		// render inside another row (the model picker folds intentGateModel /
-		// intentGateReasoningEffort into the intentGateProvider row; their
-		// `when` matches the carrier row by declaration). Field-less custom
-		// nodes (maintenance/permission panels) hang in the same tree.
+		const CLASSIFIER_LLM_OR_JEV = Object.freeze({ any: Object.freeze([CLASSIFIER_LLM, CLASSIFIER_JEV]) });
+		// The GROUPS field table. Every group: { id, page?, fields }. page is
+		// "main" (default when absent) or "routing" — the model-routing groups
+		// form the separate routing settings page (WeirCard/WeirCardController
+		// filter by it; validateLayout rejects any other value). Every node:
+		// { field?, kind, values?, display?, when?, parent?, folded?, slot? }.
+		// kind: boolean | enum | number | text | custom. An enum node may set
+		// `display: "select"` to render a compact native dropdown instead of the
+		// segmented control (long option labels squeeze the row label). `custom`
+		// nodes carry a render `slot` identifier and share parent/when with
+		// plain rows; a custom node with a `field` is text-backed at the form
+		// layer. `folded` fields stay in the form but render inside another row
+		// (the model picker folds intentGateModel / intentGateReasoningEffort
+		// into the intentGateProvider row; their `when` matches the carrier row
+		// by declaration). Field-less custom nodes (maintenance/permission
+		// panels) hang in the same tree. Keys marked page:false in
+		// src/settings/sections.js (CONFIG_FACE_ONLY_KEYS) never appear here —
+		// config-face-only by declaration, pinned by test.
 		const GROUPS = [
 			{ id: "intent", fields: [
 				{ field: "intentGateClassifier", kind: "enum", values: ["regex", "llm", "jev"] },
 				{ field: "intentGateProvider", kind: "custom", slot: "modelPicker", when: CLASSIFIER_LLM },
 				{ field: "intentGateModel", kind: "text", folded: true, when: CLASSIFIER_LLM },
 				{ field: "intentGateReasoningEffort", kind: "text", folded: true, when: CLASSIFIER_LLM },
-				{ field: "intentGateTimeoutMs", kind: "number" },
+				{ field: "intentGateTimeoutMs", kind: "number", when: CLASSIFIER_LLM_OR_JEV },
 				{ field: "jevEndpoint", kind: "text", when: CLASSIFIER_JEV },
 				{ field: "jevModel", kind: "text", when: CLASSIFIER_JEV },
 				{ field: "jevApiKeyEnv", kind: "text", when: CLASSIFIER_JEV }
 			] },
-			{ id: "delegate", fields: [
+			{ id: "routingCategories", page: "routing", fields: [
 				{ field: "delegateCategoryChains", kind: "custom", slot: "chainEditor" },
-				{ field: "delegateAgentChains", kind: "custom", slot: "agentChainEditor" },
-				{ field: "delegateDisabledCategories", kind: "custom", slot: "disabledCategoriesEditor" },
+				{ field: "delegateDisabledCategories", kind: "custom", slot: "disabledCategoriesEditor" }
+			] },
+			{ id: "routingAgents", page: "routing", fields: [
+				{ field: "delegateAgentChains", kind: "custom", slot: "agentChainEditor" }
+			] },
+			{ id: "routingSupervision", page: "routing", fields: [
 				{ field: "supervisionMaxRetries", kind: "number" },
 				{ field: "supervisionInitialBackoffMs", kind: "number" },
 				{ field: "supervisionMaxBackoffMs", kind: "number" }
@@ -87,9 +97,7 @@ window.__ModuleLoader__.load({
 			{ id: "todo", fields: [
 				{ field: "todoEnabled", kind: "boolean" },
 				{ field: "todoMaxConsecutive", kind: "number", parent: "todoEnabled", when: enabledWhen("todoEnabled") },
-				{ field: "todoErrorRetryMax", kind: "number", parent: "todoEnabled", when: enabledWhen("todoEnabled") },
-				{ field: "todoErrorBackoffBaseMs", kind: "number", parent: "todoEnabled", when: enabledWhen("todoEnabled") },
-				{ field: "todoErrorBackoffCapMs", kind: "number", parent: "todoEnabled", when: enabledWhen("todoEnabled") }
+				{ field: "todoErrorRetryMax", kind: "number", parent: "todoEnabled", when: enabledWhen("todoEnabled") }
 			] },
 			{ id: "guard", fields: [
 				{ field: "guardEnabled", kind: "boolean" },
@@ -101,11 +109,6 @@ window.__ModuleLoader__.load({
 				{ field: "editLockEnabled", kind: "boolean" },
 				{ field: "editLockAutoResume", kind: "boolean", parent: "editLockEnabled", when: enabledWhen("editLockEnabled") },
 				{ field: "editLockStaleSweep", kind: "boolean", parent: "editLockEnabled", when: enabledWhen("editLockEnabled") },
-				{ field: "editLockHoldDefaultMinutes", kind: "number", parent: "editLockEnabled", when: enabledWhen("editLockEnabled") },
-				{ field: "editLockHoldSingleMaxMinutes", kind: "number", parent: "editLockEnabled", when: enabledWhen("editLockEnabled") },
-				{ field: "editLockHoldCumulativeMaxMinutes", kind: "number", parent: "editLockEnabled", when: enabledWhen("editLockEnabled") },
-				{ field: "editLockNudgeAttempts", kind: "number", parent: "editLockEnabled", when: enabledWhen("editLockEnabled") },
-				{ field: "editLockNudgeFallback", kind: "text", parent: "editLockEnabled", when: enabledWhen("editLockEnabled") },
 				// Diagnostics must remain reachable when enforcement is off.
 				{ kind: "custom", slot: "editLockMaintenance" }
 			] },
@@ -127,9 +130,6 @@ window.__ModuleLoader__.load({
 			] },
 			{ id: "lsp", fields: [
 				{ field: "lspEnabled", kind: "boolean" },
-				{ field: "lspIdleMs", kind: "number", parent: "lspEnabled", when: enabledWhen("lspEnabled") },
-				{ field: "lspRequestTimeoutMs", kind: "number", parent: "lspEnabled", when: enabledWhen("lspEnabled") },
-				{ field: "lspDiagnosticsWaitMs", kind: "number", parent: "lspEnabled", when: enabledWhen("lspEnabled") },
 				// The raw lspServers JSON row is folded into the manager row: one
 				// custom node carrying the field (the robashList pattern —
 				// text-backed at the form layer via specFor), so the panel owns the
@@ -149,19 +149,25 @@ window.__ModuleLoader__.load({
 				// confirms its platform (self-gating), so it stays unconditional
 				// here even as a custom node in the tree.
 				{ kind: "custom", slot: "notifyPermissions" }
-			] },
-			// Session blackboard (2.4a): the write-token TTL leaves
-			// config-face-only and rides its own group. A single live number row
-			// (volatile config — no restart marker, no master switch).
-			{ id: "blackboard", fields: [
-				{ field: "blackboardWriteTokenTtlMinutes", kind: "number" }
 			] }
 		];
 		// Form fields: every node that names a flat settings key (custom
-		// panels without a field render only). Order matches the pre-overhaul
-		// flat table exactly — test pins this list.
+		// panels without a field render only), in GROUPS declaration order
+		// across both pages — test pins this list.
 		const FIELDS = GROUPS.flatMap((group) => group.fields).filter((descriptor) => typeof descriptor.field === "string");
 		const FIELD_BY_NAME = Object.fromEntries(FIELDS.map((descriptor) => [descriptor.field, descriptor]));
+		// The page one field's group belongs to ("main" when the group declares
+		// no page): the controller's form specs and projection cover exactly the
+		// page's fields, and WeirCard renders only the page's groups.
+		const FIELD_PAGE = new Map();
+		for (const group of GROUPS) {
+			for (const node of group.fields) {
+				if (typeof node.field === "string") FIELD_PAGE.set(node.field, group.page ?? "main");
+			}
+		}
+		function fieldsForPage(page) {
+			return FIELDS.filter((descriptor) => FIELD_PAGE.get(descriptor.field) === page);
+		}
 		/** Product defaults of every flat settings key with a concrete
 		 * default — hand-maintained mirror of FIELD_DEFAULTS in
 		 * src/settings/sections.js (same-package sync require is impossible
@@ -352,8 +358,14 @@ window.__ModuleLoader__.load({
 		}
 		/** Fail-loud declaration validation, run at module load: unknown or
 		 * cross-group parents, parent cycles, conditions on unknown keys or
-		 * unknown env facts — every error names the offending key. */
+		 * unknown env facts, an invalid group page — every error names the
+		 * offending key or group. */
 		function validateLayout(groups) {
+			for (const group of groups) {
+				if (group.page !== void 0 && group.page !== "main" && group.page !== "routing") {
+					throw settingsLayoutError(`group '${String(group.id)}' declares an invalid page '${String(group.page)}'`);
+				}
+			}
 			const keyToGroup = new Map();
 			for (const group of groups) {
 				for (const node of group.fields) {
@@ -409,7 +421,7 @@ window.__ModuleLoader__.load({
 					for (const child of node.children) assignDepth(child, depth + 1);
 				};
 				for (const root of roots) assignDepth(root, 0);
-				return { id: group.id, roots };
+				return { id: group.id, page: group.page ?? "main", roots };
 			});
 		}
 		// Declaration-time validation (D4): a bad GROUPS table fails chunk load
@@ -455,7 +467,12 @@ window.__ModuleLoader__.load({
 				readOnly: t("readOnly"),
 				saveFailed: t("saveFailed"),
 				save: t("save"),
-				saving: t("saving")
+				saving: t("saving"),
+				discard: t("discardChanges"),
+				// The save bar's pending count interpolates per render, so a
+				// function label: the host locale's second argument is the
+				// interpolation VARS object (never a fallback string).
+				pendingChanges: (n) => t("pendingChanges", { n })
 			};
 		}
 		// ---- environment facts (design D6) ----
@@ -479,14 +496,19 @@ window.__ModuleLoader__.load({
 		var WeirCardController = class {
 			form;
 			store;
-			constructor(scope, deps) {
+			constructor(scope, deps, page) {
+				// page: "main" (default) or "routing" — the form model tracks only
+				// that page's fields, so one scope hosts two independent forms (the
+				// routing page edits the same namespace, disjoint key set).
+				this.page = page === "routing" ? "routing" : "main";
+				this.fields = fieldsForPage(this.page);
 				// Prop-injected dependencies: the entry-owned settings bus (save →
 				// toggle re-check) and a getSession closure resolving the
 				// remote.session domain lazily at call time (it may not be wired
 				// yet during apply, S17). fetchEnv is the injectable environment
 				// facts read (tests); production uses the fetch above.
 				this.deps = deps;
-				this.form = new primitives.SettingsFormModel(scope, FIELDS.map(specFor));
+				this.form = new primitives.SettingsFormModel(scope, this.fields.map(specFor));
 				this.store = this.form.bind(() => this.projection());
 				// Restart-required keys touched by the last landed save, in
 				// registry order; null until such a save lands or after the
@@ -518,7 +540,7 @@ window.__ModuleLoader__.load({
 			}
 			projection() {
 				const fields = {};
-				for (const descriptor of FIELDS) {
+				for (const descriptor of this.fields) {
 					// `saved` rides along so condition evaluation can fall back
 					// to the saved value while an unparseable draft is staged
 					// (D3) — the merged field text alone cannot express it.
@@ -527,6 +549,9 @@ window.__ModuleLoader__.load({
 				return {
 					...this.form.shell(),
 					fields,
+					// Staged-write count for the save bar's pending label —
+					// plan() is a pure read (the same read save() plans from).
+					pendingCount: this.form.plan().length,
 					restartReminder: this.restartReminder,
 					env: this.env
 				};
@@ -755,10 +780,65 @@ window.__ModuleLoader__.load({
 			if (picker === void 0 || picker === null) return manualFallback;
 			return react_jsx_runtime.jsx(picker.ModelPickerBoundary, { fallback: manualFallback, children: pickerRow(picker) });
 		}
+		// ---- floating save bar + local form shell ----
+		// The bar renders ONLY while the form is dirty — a clean page gets no
+		// new visual noise. It sits in the normal flow as the form's last
+		// element with position: sticky, so once the page scrolls it pins to
+		// the bottom edge of the settings scroll container. Chrome mirrors the
+		// host's Toast surface (dark in BOTH themes) instead of the group cards:
+		// a floating action bar must read as a surface ABOVE the rows, not as
+		// one more row. Colors only from theme tokens, geometry hardcoded.
+		const saveBarStyle = { position: "sticky", bottom: "12px", zIndex: 1, display: "flex", alignItems: "center", justifyContent: "space-between", gap: "12px", marginTop: "12px", padding: "10px 14px", background: "var(--dsw-alias-toast-bg)", border: "none", borderRadius: "var(--dsw-radius-lg, 12px)", boxShadow: "var(--dsw-shadow-lv3, 0 8px 24px rgba(0,0,0,.18))" };
+		const saveBarTextStyle = { display: "flex", alignItems: "center", gap: "8px", minWidth: 0, fontSize: "12px", lineHeight: "16px", color: "var(--dsw-alias-toast-label)" };
+		// warn-label (not warn-primary) is the token designed for dark surfaces.
+		const saveBarFailedStyle = { color: "var(--dsw-alias-state-warn-label)" };
+		// Discard as a plain text action (the host toast's action pattern): the
+		// outline Button variant is tuned for regular surfaces and reads poorly
+		// on the always-dark toast surface.
+		const saveBarDiscardStyle = { background: "none", border: "none", cursor: "pointer", fontSize: "12px", lineHeight: "16px", padding: "4px 2px", color: "var(--dsw-static-deepseek-400, var(--dsw-alias-brand-primary))" };
+		const saveBarActionsStyle = { display: "flex", alignItems: "center", gap: "8px", flexShrink: 0 };
+		// The form-shell notice lines (unavailable / readOnly) keep the host
+		// contract's role="status" lines in the page's hint styling.
+		const formNoticeStyle = { fontSize: "13px", lineHeight: "18px", color: "var(--dsw-alias-label-secondary)", margin: "0 0 12px" };
+		/** Local form shell replacing the host primitives.SettingsForm (whose
+		 * footer sits at the bottom of a long page and cannot be restyled from
+		 * outside). The host contract is preserved verbatim: staged edits are
+		 * discarded on unmount (the ref follows the latest onDiscard; hooks run
+		 * before the early return so the cleanup registers in every state), an
+		 * unavailable namespace renders the notice line INSTEAD of the form,
+		 * and a read-only deployment shows the readOnly notice above the
+		 * controls. The save affordance is the sticky bar: pending count +
+		 * failure text left, discard/save right; invalid or saving disables
+		 * save (the bar existing already implies dirty). */
+		function WeirSettingsForm(props) {
+			const { state, labels } = props;
+			const discardRef = react.useRef(props.onDiscard);
+			discardRef.current = props.onDiscard;
+			react.useEffect(() => () => discardRef.current(), []);
+			if (!state.available) return react_jsx_runtime.jsx("p", { style: formNoticeStyle, role: "status", children: labels.unavailable });
+			return react_jsx_runtime.jsxs("div", { children: [
+				!state.writable ? react_jsx_runtime.jsx("p", { style: formNoticeStyle, role: "status", children: labels.readOnly, key: "read-only" }) : null,
+				props.children,
+				state.dirty ? react_jsx_runtime.jsxs("div", { style: saveBarStyle, "data-save-bar": "", children: [
+					react_jsx_runtime.jsxs("div", { style: saveBarTextStyle, children: [
+						react_jsx_runtime.jsx("span", { children: labels.pendingChanges(state.pendingCount ?? 0), key: "pending" }),
+						state.failed ? react_jsx_runtime.jsx("span", { style: saveBarFailedStyle, role: "status", children: labels.saveFailed, key: "failed" }) : null
+					] }),
+					react_jsx_runtime.jsxs("div", { style: saveBarActionsStyle, children: [
+						react_jsx_runtime.jsx("button", { type: "button", style: saveBarDiscardStyle, onClick: props.onDiscard, children: labels.discard }),
+						react_jsx_runtime.jsx(primitives.Button, { variant: "primary", size: "sm", disabled: state.invalid || state.saving, onClick: props.onSave, children: state.saving ? labels.saving : labels.save })
+					] })
+				] }, "save-bar") : null
+			] });
+		}
 		function WeirCard(props) {
 			const state = props.useWeirSettingsCard((snapshot) => snapshot);
 			const { t } = props;
-			if (props.view === "summary") return t("description");
+			// Dual-page card: props.page ("main" default, "routing") selects the
+			// summary text and the rendered group subset; conditions/restartTag/
+			// displayText are page-independent.
+			const page = props.page === "routing" ? "routing" : "main";
+			if (props.view === "summary") return t(page === "routing" ? "routingDescription" : "description");
 			const disabled = !state.writable;
 			// env three-state (D6): pending/failed hide env-gated rows only.
 			const env = state.env ?? { status: "ready", facts: {} };
@@ -893,7 +973,7 @@ window.__ModuleLoader__.load({
 			// Card sections: the tree walk prunes hidden subtrees wholesale (a
 			// hidden parent hides every descendant), and children land directly
 			// under their parent's subtree in DFS order.
-			const cards = LAYOUT.map((groupLayout) => {
+			const cards = LAYOUT.filter((groupLayout) => groupLayout.page === page).map((groupLayout) => {
 				const rows = [];
 				const walk = (node, ancestorsVisible) => {
 					const isVisible = ancestorsVisible && visible(node);
@@ -931,7 +1011,9 @@ window.__ModuleLoader__.load({
 					key: "restart-reminder"
 				}));
 			}
-			return react_jsx_runtime.jsxs(primitives.SettingsForm, {
+			// The local form shell (NOT the host primitives.SettingsForm): same
+			// contract, with the save affordance as the sticky bar above.
+			return react_jsx_runtime.jsxs(WeirSettingsForm, {
 				labels: formLabels(t),
 				state,
 				onSave: props.save,
@@ -945,9 +1027,12 @@ window.__ModuleLoader__.load({
 			gap: "var(--dsw-spacing-3, 12px)"
 		};
 		const ITEM_SLOT = "settings.weir.item";
-		const WeirSection = ({ renderSlot }) => react_jsx_runtime.jsx("div", {
+		// The section shell is page-agnostic: the composition root passes the
+		// child item slot of the page being hosted (main by default, the
+		// routing page's "settings.weir-routing.item" for the routing section).
+		const WeirSection = ({ renderSlot, slot }) => react_jsx_runtime.jsx("div", {
 			style: columnStyle,
-			children: renderSlot(ITEM_SLOT)
+			children: renderSlot(slot ?? ITEM_SLOT)
 		});
 		exports.GROUPS = GROUPS;
 		exports.BOOLEAN_DEFAULTS = BOOLEAN_DEFAULTS;
@@ -957,6 +1042,7 @@ window.__ModuleLoader__.load({
 		exports.CATEGORY_NAMES = CATEGORY_NAMES;
 		exports.RESTART_FIELDS = RESTART_FIELDS;
 		exports.FIELDS = FIELDS;
+		exports.fieldsForPage = fieldsForPage;
 		exports.ENV_FACTS = ENV_FACTS;
 		exports.evaluateCondition = evaluateCondition;
 		exports.conditionUsesEnv = conditionUsesEnv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weir-harness",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "type": "module",
   "description": "Weir \u2014 orchestrator-centric DSH agent preset: intent gate, category delegation, todo driver, pull-based background jobs, auto-compaction, hashline edit.",
   "license": "MIT",

package/src/blackboard/durable.js

@@ -186,6 +186,19 @@ export async function resolveDurableRoot(ctx, agent, runtime, mount = undefined)
         if (mount) mounts.add(mount)
         runtime.members.set(agent.id, { agent, root: id, mounts })
       }
+      // A fork (a depth-0 Session carrying parentSession) is its own board root,
+      // but its board starts as a one-time snapshot of the fork source's durable
+      // root board: seed before the first ensure can materialize an empty sidecar.
+      // Once per runtime; the no-sidecar disk check keeps it idempotent across
+      // restarts. Best-effort: a failed seed never blocks board availability.
+      const parentId = header.parentSession
+      if (typeof parentId === 'string' && parentId.length > 0) {
+        runtime.forkSeeded ??= new Set()
+        if (!runtime.forkSeeded.has(id)) {
+          runtime.forkSeeded.add(id)
+          try { await runtime.storage.seedFork(id, parentId, where.header.cwd) } catch (error) { ctx.logger?.warn?.(`blackboard fork seeding failed: ${String(error)}`) }
+        }
+      }
       runtime.kernel.bind(id, where.header.cwd)
       await runtime.kernel.ensure(id)
       if (wasLive && (runtime.revoked?.has(agent) || ctx.get?.('agents')?.get?.(agent.id) !== agent)) throw new Error('blackboard: Agent disposed while resolving its root')

package/src/blackboard/index.js

@@ -346,6 +346,50 @@ export function createBlackboardPlugin({ kernel, resolveTtl = resolveWriteTokenT
       return id
     }
 
+    /**
+     * The conversation root for a BARE session id (the remote bridge's
+     * resolve face — the side panel asks for the board it should bind
+     * before any lookup-gated verb runs). Same root semantics as boardOf
+     * and resolveDurableRoot: a depth-0 session (including a fork that
+     * still carries a parentSession) is its own root; a delegated child
+     * ascends the parentSession chain. Each hop reads the live sessions
+     * registry first, then the durable header through
+     * sessionQuery.readSession (the parentOf seam — a child between
+     * turns has no live registry entry). A hop that yields no header, a
+     * missing parent, a cycle, or the hop cap degrades to the deepest
+     * known ancestor: boards never silently cross-contaminate
+     * conversations.
+     * @param {string} sessionId
+     * @returns {Promise<string>}
+     */
+    const rootOf = async (sessionId) => {
+      const headerOf = async (/** @type {string} */ id) => {
+        try {
+          const live = ctx.get?.('sessions')?.get?.(id)
+          if (live?.header && typeof live.header === 'object') return live.header
+        } catch { /* fall through to the durable lookup */ }
+        try {
+          // readSession returns { session, events } — the session record IS
+          // the durable header (id, parentSession, delegationDepth, ...).
+          const read = await ctx.get?.('sessionQuery')?.readSession?.(id)
+          if (read?.session && typeof read.session === 'object') return read.session
+        } catch { /* an unreadable log yields no header */ }
+        return undefined
+      }
+      let id = sessionId
+      const seen = new Set([id])
+      for (let hop = 0; hop < MAX_ANCESTORS; hop++) {
+        const header = await headerOf(id)
+        if (!header) break
+        if ((header.delegationDepth ?? 0) === 0) return id
+        const parentId = header.parentSession
+        if (typeof parentId !== 'string' || parentId.length === 0 || seen.has(parentId)) break
+        seen.add(parentId)
+        id = parentId
+      }
+      return id
+    }
+
     const call = (exec, action) => {
       if (lifecycle) return lifecycle.run(exec?.agent, root => { exec?.signal?.throwIfAborted?.(); return action(root) })
       const id = boardOf(exec?.agent)
@@ -382,7 +426,7 @@ export function createBlackboardPlugin({ kernel, resolveTtl = resolveWriteTokenT
       resolveMainAgent: agent => agent,
       logger: ctx.logger,
     })
-    const offBridge = feedBlackboardRemoteBridge({ kernel: kernelInstance, boardOf, run: lifecycle?.run, ttlMs, requestPromotion: async (/** @type {any} */ agent) => {
+    const offBridge = feedBlackboardRemoteBridge({ kernel: kernelInstance, boardOf, rootOf, run: lifecycle?.run, ttlMs, requestPromotion: async (/** @type {any} */ agent) => {
       const root = await boardOf(agent)
       const main = root === agent.id ? agent : ctx.get?.('agents')?.get?.(root)
       if (!main) throw new Error('blackboard: root Agent is not live for promotion')

package/src/blackboard/remote.js

@@ -16,11 +16,12 @@
 // WIRE CONTRACT (pinned — the parallel panel lane builds against this exact
 // shape; see docs/features/blackboard.md 面板数据通道):
 //
-//   namespace `weirBlackboard`; every method takes one JSON `args` object.
-//   The acting session rides the `agent` lookup parameter (wire `agentId`,
-//   scope context `agent`) — the panel page's current session injects it the
-//   same way the stock `fileReferences` remote does, so the domain signatures
-//   below need no session field:
+//   namespace `weirBlackboard`. The seven board verbs each take one JSON
+//   `args` object, and the acting session rides the `agent` lookup
+//   parameter (wire `agentId`, scope context `agent`) — the panel page's
+//   current session injects it the same way the stock `fileReferences`
+//   remote does, so the domain signatures below need no session field.
+//   The eighth method, resolve, is the deliberate exception named below.
 //
 //   - list({ type?, query? }) → { entries: [{ key, entryType, summary,
 //     readCount, subscribeCount, updatedAt, promoted? }] }
@@ -40,6 +41,16 @@
 //   - markPromoted({ key, destination }) → { ok: true, destination }
 //                             | { ok: false, error } — makes the entry
 //                             read-only with the promoted marker
+//   - resolve                  → { sessionId } — the panel's root
+//                             resolution (slice 4): NO scope, NO agent
+//                             lookup. The gateway's agent lookup refuses
+//                             subagent-owned sessions before this service
+//                             can run (the subagent-panel 404 root cause),
+//                             so the browsing session id crosses as a bare
+//                             JSON `agentId` parameter (source 'json' — the
+//                             capability-remote precedent) and the answer
+//                             is the conversation root whose board the
+//                             panel binds before any lookup-gated verb.
 //
 //   `token` is an opaque per-acquisition identifier (the authority itself is
 //   the acting session's live kernel token, re-checked at every mutation);
@@ -56,7 +67,7 @@
 export const BLACKBOARD_REMOTE_SERVICE_KEY = 'weirBlackboardRemote'
 /** The wire namespace: POST /api/weirBlackboard/<method>, client ctx.remote.weirBlackboard.*. */
 export const BLACKBOARD_REMOTE_NAMESPACE = 'weirBlackboard'
-/** The seven methods, each taking one JSON `args` parameter plus the acting-session lookup. */
+/** The seven board verbs, each taking one JSON `args` parameter plus the acting-session lookup. The eighth wire method, resolve, is built separately in the contribution (no lookup, no scope). */
 export const BLACKBOARD_REMOTE_METHODS = Object.freeze(['list', 'read', 'apply', 'write', 'remove', 'requestPromotion', 'markPromoted'])
 /** The wire package identity (distinct from 'weir-harness' — the capability-remote contribution already owns that package face). */
 const BLACKBOARD_REMOTE_PACKAGE = 'weir-blackboard'
@@ -90,6 +101,7 @@ export class BlackboardRemoteError extends Error {
  * module-level slot pattern as the capability read bridge. Faces:
  *   kernel()  — the shared arbitration kernel (list/read/apply/write/deleteKey)
  *   boardOf(agent) — conversation-root board id for an agent handle
+ *   rootOf(sessionId) — conversation-root session id for a BARE session id
  *   ttlMs()   — the settings-driven write-token TTL in milliseconds
  */
 let bridgeFaces = null
@@ -97,7 +109,7 @@ let bridgeFaces = null
 /**
  * Feed the bridge (blackboard plugin apply). Returns the unregister the plugin
  * disposes with its own lifecycle.
- * @param {{ kernel: any, boardOf: (agent: any) => string | undefined, ttlMs: () => number }} faces
+ * @param {{ kernel: any, boardOf: (agent: any) => string | undefined, rootOf?: (sessionId: string) => Promise<string>, ttlMs: () => number }} faces
  */
 export function feedBlackboardRemoteBridge(faces) {
   bridgeFaces = faces
@@ -155,7 +167,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
    * @param {any} agent
    * @returns {{ sessionId: string, boardId: string, faces: { kernel: any, boardOf: Function, ttlMs: Function } }}
    */
-  async function resolve(agent) {
+  async function resolveActing(agent) {
     if (!ensure()) throw new BlackboardRemoteError('channel-unavailable', 'blackboard remote is not registered with the gateway')
     const faces = bridgeFor()
     if (!faces) throw new BlackboardRemoteError('bridge-absent', 'blackboard remote is not offered (non-Weir preset or unmounted bridge)')
@@ -187,7 +199,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
     /** Aggregate rows: key + entryType + summary + counts, never content. */
     async list(agent, args) {
       return payloadWrap('list', async () => {
-        const { boardId, faces } = await resolve(agent)
+        const { boardId, faces } = await resolveActing(agent)
         const rows = await faces.kernel.list(boardId, { entryType: args?.type, query: args?.query })
         return { entries: rows.map((/** @type {any} */ entry) => wireEntry(entry)) }
       })
@@ -198,7 +210,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
      * the agent-tool path's reuse evidence, not a page-view metric. */
     async read(agent, args) {
       return payloadWrap('read', async () => {
-        const { boardId, faces } = await resolve(agent)
+        const { boardId, faces } = await resolveActing(agent)
         const result = await faces.kernel.read(boardId, args?.keys ?? [], { count: false })
         return { entries: result.found.map((/** @type {any} */ entry) => wireEntry(entry, { content: true })) }
       })
@@ -207,7 +219,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
     /** Acquire the one-shot write authority for one key (auto-subscribes on contention; a promoted key refuses explicitly). */
     async apply(agent, args) {
       return payloadWrap('apply', async () => {
-        const { sessionId, boardId, faces } = await resolve(agent)
+        const { sessionId, boardId, faces } = await resolveActing(agent)
         const result = await faces.kernel.apply(boardId, { holderId: sessionId, key: args?.key, ttlMs: faces.ttlMs() })
         if (result.status === 'contended') return { acquired: false, holder: result.holder, subscribed: true }
         if (result.status === 'promoted') return { acquired: false, promoted: true, destination: result.destination }
@@ -218,7 +230,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
     /** Create or update one entry under the acting session's live write authority. */
     async write(agent, args) {
       try {
-        const { sessionId, boardId, faces } = await resolve(agent)
+        const { sessionId, boardId, faces } = await resolveActing(agent)
         const result = await faces.kernel.write(boardId, {
           holderId: sessionId,
           key: args?.key,
@@ -249,7 +261,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
     /** Delete one entry under the acting session's live write authority. */
     async remove(agent, args) {
       try {
-        const { sessionId, boardId, faces } = await resolve(agent)
+        const { sessionId, boardId, faces } = await resolveActing(agent)
         const result = await faces.kernel.deleteKey(boardId, { holderId: sessionId, key: args?.key })
         if (result.status === 'missing') return { ok: false, error: `blackboard key "${result.key}" does not exist` }
         if (result.status === 'promoted') {
@@ -271,7 +283,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
     /** Request the promotion-evaluation brief into the session's main agent (slice 3). Folds failures like the mutations. */
     async requestPromotion(agent, args) {
       try {
-        const { faces } = await resolve(agent)
+        const { faces } = await resolveActing(agent)
         if (typeof faces.requestPromotion !== 'function') {
           return { ok: false, error: 'the blackboard bridge does not offer promotion requests' }
         }
@@ -288,7 +300,7 @@ export function createBlackboardRemoteService(dependencies = {}) {
     /** Mark one entry promoted under the user-adjudicated destination (slice 3); marking is an annotation, not a payload mutation. */
     async markPromoted(agent, args) {
       try {
-        const { boardId, faces } = await resolve(agent)
+        const { boardId, faces } = await resolveActing(agent)
         const result = await faces.kernel.markPromoted(boardId, { key: args?.key, destination: args?.destination })
         if (result.status === 'missing') return { ok: false, error: `blackboard key "${result.key}" does not exist` }
         if (result.status === 'already-promoted') return { ok: true, destination: result.destination, alreadyPromoted: true }
@@ -300,6 +312,28 @@ export function createBlackboardRemoteService(dependencies = {}) {
         return { ok: false, error }
       }
     },
+
+    /**
+     * The panel's root resolution (slice 4): the browsing session id
+     * crosses as a bare JSON value — NO agent lookup, NO scope — because
+     * the gateway's lookup refuses subagent-owned sessions before this
+     * service can run. Answers the conversation root whose board the
+     * panel binds; a bridge without the rootOf face (an older blackboard
+     * plugin) or a face returning an unusable id degrades to the
+     * browsing id itself, which is exactly the pre-resolve behavior.
+     */
+    async resolve(sessionId) {
+      return payloadWrap('resolve', async () => {
+        if (!ensure()) throw new BlackboardRemoteError('channel-unavailable', 'blackboard remote is not registered with the gateway')
+        const faces = bridgeFor()
+        if (!faces) throw new BlackboardRemoteError('bridge-absent', 'blackboard remote is not offered (non-Weir preset or unmounted bridge)')
+        const id = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : undefined
+        if (id === undefined) throw new BlackboardRemoteError('unknown-session', 'blackboard remote resolve: the browsing session identity is unavailable')
+        if (typeof faces.rootOf !== 'function') return { sessionId: id }
+        const root = await faces.rootOf(id)
+        return { sessionId: typeof root === 'string' && root.length > 0 ? root : id }
+      })
+    },
   }
 }
 
@@ -321,7 +355,8 @@ export function blackboardRemoteContribution() {
     face: 'host',
     schemas: [],
     model: { services: [], events: [], objects: [] },
-    invocations: BLACKBOARD_REMOTE_METHODS.map(method => ({
+    invocations: [
+      ...BLACKBOARD_REMOTE_METHODS.map(method => ({
       id: `${BLACKBOARD_REMOTE_PACKAGE}.${BLACKBOARD_REMOTE_NAMESPACE}.${method}`,
       service: BLACKBOARD_REMOTE_SERVICE_KEY,
       namespace: BLACKBOARD_REMOTE_NAMESPACE,
@@ -334,6 +369,24 @@ export function blackboardRemoteContribution() {
       ],
       result: { mode: 'src-json' },
     })),
+      // The eighth invocation, resolve, deliberately breaks the shared
+      // shape: NO agent-lookup parameter, NO scope projection — the
+      // gateway's agent lookup refuses subagent-owned sessions before
+      // this service can run (the subagent-panel 404 root cause), so the
+      // browsing session id crosses as a bare JSON value on the same
+      // `agentId` wire field (the capability-remote precedent, src-json).
+      {
+        id: `${BLACKBOARD_REMOTE_PACKAGE}.${BLACKBOARD_REMOTE_NAMESPACE}.resolve`,
+        service: BLACKBOARD_REMOTE_SERVICE_KEY,
+        namespace: BLACKBOARD_REMOTE_NAMESPACE,
+        method: 'resolve',
+        invocation: { kind: 'direct' },
+        parameters: [
+          { name: 'sessionId', wire: 'agentId', source: 'json', codec: { mode: 'src-json' } },
+        ],
+        result: { mode: 'src-json' },
+      },
+    ],
   }
 }