@ran-sh/dsh-crew 1.0.3 → 1.1.0

package/codex/AGENTS.md

@@ -1,92 +1,101 @@
-# Global capability-aware delegation policy
-
-The main Codex agent owns the user's task from planning through final delivery.
-DSH Crew is an execution and review capability that Codex may use after
-discovering what the current environment actually supports.
-
-## Discover capabilities before delegation
-
-- Before delegating substantial work, query DSH Crew's authoritative live
-  configuration, capability, and readiness surfaces.
-- Discover capabilities dynamically from the returned contracts. Do not rely
-  on a hard-coded list of roles, models, providers, tools, modes, or optional
-  features; newly added capabilities should be considered automatically.
-- For every relevant capability, respect its reported availability, activation
-  state, invocation mode, constraints, dependencies, and readiness evidence.
-- Treat installed, configured, enabled, and callable as different states. Use a
-  capability only when the complete live execution path is ready.
-- Keep the capability snapshot for the current plan, and refresh it after a
-  relevant configuration change or an availability, routing, credential,
-  compatibility, or activation failure.
-- If discovery is unavailable or evidence is incomplete, fail closed: do not
-  invent capabilities or repeatedly dispatch blind retries. If DSH Crew was
-  selected for the task, apply the operator decision gate below.
-
-## Operator decision gate when DSH Crew is unavailable
-
-- Once Codex has selected DSH Crew for any work unit, any condition that makes
-  the required Crew capability unavailable or non-callable is a mandatory
-  pause point, regardless of cause.
-- At this pause point, do not continue implementation, silently fall back,
-  choose another execution path, or repair/reconfigure DSH Crew without new
-  operator direction. Perform only the read-only diagnosis needed to report
-  the blocker accurately.
-- Report the unavailable capability, bounded reason and evidence, and completed
-  work. Then wait for the operator to choose one direction:
-  1. Repair or restore DSH Crew, then continue through DSH Crew.
-  2. Do not repair DSH Crew; continue with the main Codex agent.
-- Resume only after the operator gives a new instruction. If repair is chosen,
-  verify live capability again before dispatch. If local execution is chosen,
-  state that the affected work is no longer independently delegated.
-- This gate applies only after DSH Crew has been selected or explicitly
-  requested. It does not force a pause when initial planning decides DSH Crew
-  provides no benefit and the task should remain with the main agent.
-
-## Decide what to delegate
-
-- Decompose the request into bounded work units before choosing an executor.
-- Match each unit against discovered capabilities. Use DSH Crew only where it
-  provides a clear execution, isolation, parallelism, specialization, or
-  independent-review benefit.
-- Delegate the smallest coherent unit that can be completed and verified
-  independently. Do not delegate an entire request merely because it is large.
-- Keep ambiguity, dependency ordering, cross-cutting decisions, conflict
-  resolution, external side effects, final integration, and user communication
-  in the main Codex agent.
-- Respect reported concurrency and isolation limits. Parallelize only
-  independent units with explicit, non-overlapping ownership.
-- Simple questions, explanations, small read-only inspections, and genuinely
-  trivial edits should normally remain in the main agent.
-- Explicit user instructions override default routing, but never safety or
-  capability boundaries.
-
-## Execute and verify
-
-- Give each delegated unit a concrete objective, owned scope, workspace
-  context, constraints, and required validation evidence.
-- Prefer isolated execution for code changes when supported. Review work must
-  remain read-only.
-- Consume compact structured results and canonical events. Do not move
-  unbounded transcripts, raw provider payloads, credentials, or unnecessary
-  patch content between agents.
-- The main agent must validate results, tests, changed scope, unresolved risks,
-  and completion state before accepting delegated work.
-
-## Review policy
-
-- Use available independent review for non-trivial code changes when its live
-  invocation policy permits automatic use or the user requests manual use.
-- Never bypass a manual, disabled, unavailable, or restricted review boundary.
-- Treat requested changes, incomplete structured results, or missing direct
-  evidence as not approved.
-- If selected DSH Crew review cannot run, apply the operator decision gate. The
-  main agent may review locally only after the operator selects that path.
-
-## Authority and completion
-
-- Delegation does not broaden authority. Publishing, pushing, messaging,
-  credential changes, account actions, destructive operations, and other
-  external effects still require authority from the user's request.
-- Do not present delegated work as complete until validation passes, structured
-  results are complete, integration is checked, and permitted review
-  requirements are satisfied or transparently reported as unavailable.
+# Global capability-aware delegation policy
+
+The main Codex agent owns the user's task from planning through final delivery.
+DSH Crew is an execution and review capability that Codex may use after
+discovering what the current environment actually supports.
+
+## Discover capabilities before delegation
+
+- Before delegating substantial work, query DSH Crew's authoritative live
+  configuration, capability, and readiness surfaces.
+- Discover capabilities dynamically from the returned contracts. Do not rely
+  on a hard-coded list of roles, models, providers, tools, modes, or optional
+  features; newly added capabilities should be considered automatically.
+- For every relevant capability, respect its reported availability, activation
+  state, invocation mode, constraints, dependencies, and readiness evidence.
+- Treat installed, configured, enabled, and callable as different states. Use a
+  capability only when the complete live execution path is ready.
+- Keep the capability snapshot for the current plan, and refresh it after a
+  relevant configuration change or an availability, routing, credential,
+  compatibility, or activation failure.
+- If discovery is unavailable or evidence is incomplete, fail closed: do not
+  invent capabilities or repeatedly dispatch blind retries. If DSH Crew was
+  selected for the task, apply the operator decision gate below.
+
+## Operator decision gate when DSH Crew is unavailable
+
+- Once Codex has selected DSH Crew for any work unit, any condition that makes
+  the required Crew capability unavailable or non-callable is a mandatory
+  pause point, regardless of cause.
+- At this pause point, do not continue implementation, silently fall back,
+  choose another execution path, or repair/reconfigure DSH Crew without new
+  operator direction. Perform only the read-only diagnosis needed to report
+  the blocker accurately.
+- Report the unavailable capability, bounded reason and evidence, and completed
+  work. Then wait for the operator to choose one direction:
+  1. Repair or restore DSH Crew, then continue through DSH Crew.
+  2. Do not repair DSH Crew; continue with the main Codex agent.
+- Resume only after the operator gives a new instruction. If repair is chosen,
+  verify live capability again before dispatch. If local execution is chosen,
+  state that the affected work is no longer independently delegated.
+- This gate applies only after DSH Crew has been selected or explicitly
+  requested. It does not force a pause when initial planning decides DSH Crew
+  provides no benefit and the task should remain with the main agent.
+
+## Decide what to delegate
+
+- Decompose the request into bounded work units before choosing an executor.
+- Match each unit against discovered capabilities. Use DSH Crew only where it
+  provides a clear execution, isolation, parallelism, specialization, or
+  independent-review benefit.
+- Delegate the smallest coherent unit that can be completed and verified
+  independently. Do not delegate an entire request merely because it is large.
+- Keep ambiguity, dependency ordering, cross-cutting decisions, conflict
+  resolution, external side effects, final integration, and user communication
+  in the main Codex agent.
+- Respect reported concurrency and isolation limits. Parallelize only
+  independent units with explicit, non-overlapping ownership.
+- Simple questions, explanations, small read-only inspections, and genuinely
+  trivial edits should normally remain in the main agent.
+- Explicit user instructions override default routing, but never safety or
+  capability boundaries.
+
+## Execute and verify
+
+- Give each delegated unit a concrete objective, owned scope, workspace
+  context, constraints, and required validation evidence.
+- Prefer isolated execution for code changes when supported. Review work must
+  remain read-only.
+- Consume compact structured results and canonical events. Do not move
+  unbounded transcripts, raw provider payloads, credentials, or unnecessary
+  patch content between agents.
+- The main agent must validate results, tests, changed scope, unresolved risks,
+  and completion state before accepting delegated work.
+
+## Review policy
+
+- Use available independent review for non-trivial code changes when its live
+  invocation policy permits automatic use or the user requests manual use.
+- Never bypass a manual, disabled, unavailable, or restricted review boundary.
+- Treat requested changes, incomplete structured results, or missing direct
+  evidence as not approved.
+- If selected DSH Crew review cannot run, apply the operator decision gate. The
+  main agent may review locally only after the operator selects that path.
+
+## Authority and completion
+
+- Delegation does not broaden authority. Publishing, pushing, messaging,
+  credential changes, account actions, destructive operations, and other
+  external effects still require authority from the user's request.
+- Do not present delegated work as complete until validation passes, structured
+  results are complete, integration is checked, and permitted review
+  requirements are satisfied or transparently reported as unavailable.
+
+## Harness upgrade redlines
+
+- Never install, update, register, unlink, repair, or mutate anything under ~/.dsh.
+- DSH Crew runtime upgrades must go through the Crew-owned installer and DSH_HOME.
+- Never use direct pnpm/npm/dsh plugin operations against the official web profile.
+- Preparing a Harness upgrade must not restart 3080 or 3210.
+- Standalone workers launch through the official DSH SDK profile contract; dsh-sdk-jsonrpc-demo is obsolete.
+- Legacy 3080 bridge must never be used for 3210 lifecycle/restart/rollback.

package/docs/ui-surfaces.md

@@ -1,46 +1,66 @@
-# 3080 and 3210 UI responsibilities
+# 3210 and 3080 UI responsibilities
 
-DSH Crew deliberately presents two different user experiences from one shared
-client build.
+DSH Crew presents two different user experiences from two independently built
+client bundles. The native 3210 page is the canonical full control plane;
+the official 3080 page is an optional narrow quick-controls panel.
 
-## 3080: daily Crew control plane
+## 3210: canonical full control plane
 
-The official Harness `web` profile on `127.0.0.1:3080` owns day-to-day Crew
-management:
+The Crew-owned `dsh-crew` profile on `127.0.0.1:3210` owns day-to-day Crew
+management AND model execution:
 
 - Crew workflow and global enablement
 - Worker and Reviewer policy
 - model priority, fallback, review, and adaptive routing
-- runtime and activation-boundary information
-- Codex, Claude, and ZCode installation actions and structured readiness
+- multimodal (vision/imagegen) capability switches
+- providers lifecycle (migrate/delete/rollback/quarantine)
+- credential references lifecycle
+- workspaces, presets, jobs
+- installation integrations (Codex, Claude, ZCode)
 - task status and bounded model-invocation summaries
-- the link to the underlying 3210 Crew Harness
 
-The lightweight official-web bridge keeps these requests same-origin and
-proxies only the `/_dsh/dsh-crew/*` contract to the isolated backend.
+Bundle: `lib/client.js` (module `@ran-sh/dsh-crew`), built from
+`src/client/entry.tsx`.
 
-## 3210: isolated native Harness
+## 3080: optional quick-controls surface
 
-The Crew-owned `dsh-crew` profile on `127.0.0.1:3210` owns model execution and
-low-level Harness configuration. Its native Harness menus remain the place for
-Providers, Harness Models, Agent presets, and native runtime settings.
+The official Harness `web` profile on `127.0.0.1:3080` may host a NARROW
+quick-controls card — and nothing else:
 
-The DSH Crew settings entry on this surface is intentionally diagnostics-only:
-it shows bounded runtime identity and a link back to 3080. It does not duplicate
-Worker/Reviewer policy, host integrations, tasks, or orchestration controls.
+- master switch (`subagents_enabled`)
+- Flash / Pro model priority lists (add/remove/reorder only)
+- vision / imagegen toggles + providers (restart-pending flow)
+- deep link to the 3210 full control plane (`http://127.0.0.1:3210/`)
+
+Bundle: `official-web-bridge/lib/client.js` (module
+`@ran-sh/dsh-crew-web-bridge`), built from `src/client/quick-entry.tsx`.
+It physically contains none of the full control-plane code (no credential
+purge, no provider delete/migration, no install integration).
+
+The 3080 bridge proxies ONLY four exact endpoints to 3210:
+`quick-config`, `quick-status`, `runtime/restart-request`,
+`runtime/restart-status`. Everything else on the Crew namespace is 404 on
+3080, and `/supervisor/restart` returns 410 Gone pointing at 3210.
+
+The official `~/.dsh` tree is strictly read-only for Crew; the 3080 quick
+surface itself is optional — Crew works fully with 3080 closed.
+
+## UNKNOWN: diagnostics only
+
+Unknown surfaces render diagnostics and never gain write authority.
 
 ## Surface detection and failure behavior
 
 The client does not infer responsibility from a hard-coded browser port. It
 uses two same-origin, structured signals:
 
-1. `/_dsh/dsh-crew/bridge-status` identifies the official bridge control plane.
+1. `/_dsh/dsh-crew/bridge-status` identifies the official quick bridge.
 2. `/_dsh/dsh-crew/runtime` identifies the native Crew-owned runtime.
 
 The bridge signal wins on 3080 because the proxied runtime response correctly
 describes the 3210 backend. If neither contract can be verified, the client
-fails closed to the minimal diagnostics view. Missing evidence never enables
-the full control plane and never becomes `READY`.
+fails closed to the diagnostics view. Missing evidence never enables the
+full control plane and never becomes `READY`.
 
 The split changes presentation only. Crew state, credentials, routing policy,
 and model execution remain isolated under the Crew-owned home and profile.
@@ -63,3 +83,10 @@ they do not authenticate local users. If a deployment ever needs to separate
 local principals, add a per-install random token to state-changing calls and
 inject it server-side in the bridge — do not use browser `Origin` as
 authentication.
+
+## Process ownership
+
+The Windows launcher supervisor (`windows/start-dsh-crew.ps1` watch mode) is
+the ONLY process authority for 3210. The 3080 bridge never spawns, owns, or
+kills 3210. Restart and maintenance go through durable request files the hub
+writes and the launcher executes (`supervisor/restart-request.mjs`).

package/lib/client.js

@@ -195,7 +195,7 @@ function runtimeState(runtime, readinessSnapshot) {
 }
 function bridgeState(surface) {
 	if (surface === "official-bridge") return READINESS_STATES.READY;
-	if (surface === "native-crew-harness") return READINESS_STATES.UNAVAILABLE;
+	if (surface === "native-crew-harness") return READINESS_STATES.UNKNOWN;
 	return READINESS_STATES.UNKNOWN;
 }
 /** Project only structured, non-secret installer/runtime evidence. */
@@ -265,12 +265,31 @@ function classifyCrewSurface({ bridgeStatus, runtime } = {}) {
 	if (runtime?.ok === true && runtime.service === "dsh-crew-hub" && (runtime.surface === CREW_UI_SURFACES.NATIVE || runtime.surface === void 0)) return CREW_UI_SURFACES.NATIVE;
 	return CREW_UI_SURFACES.UNKNOWN;
 }
+/**
+* Surface capability model. The NATIVE 3210 Crew harness is the single full
+* control plane; the OFFICIAL 3080 surface is a narrow quick-controls panel
+* (total switch, flash/pro model priority, vision/imagegen toggles) plus a
+* deep link back to 3210. Unknown surfaces get diagnostics only — never write
+* authority. This replaces the old binary full-vs-minimal assumption.
+*/
 function surfaceResponsibilities(surface) {
-	const fullControlPlane = surface === CREW_UI_SURFACES.OFFICIAL;
-	return {
-		fullControlPlane,
-		minimalDiagnostics: !fullControlPlane
-	};
+	switch (surface) {
+		case CREW_UI_SURFACES.NATIVE: return {
+			fullControlPlane: true,
+			quickControlPlane: true,
+			diagnostics: true
+		};
+		case CREW_UI_SURFACES.OFFICIAL: return {
+			fullControlPlane: false,
+			quickControlPlane: true,
+			diagnostics: true
+		};
+		default: return {
+			fullControlPlane: false,
+			quickControlPlane: false,
+			diagnostics: true
+		};
+	}
 }
 //#endregion
 //#region src/client/task-telemetry.mjs
@@ -1591,7 +1610,7 @@ function WorkersPanel({ ctx }) {
 		} catch {}
 	}, [get]);
 	(0, react.useEffect)(() => {
-		if (surface !== CREW_UI_SURFACES.OFFICIAL) return void 0;
+		if (!surfaceResponsibilities(surface).fullControlPlane) return void 0;
 		refreshAll();
 		const timer = setInterval(() => {
 			Promise.all([get("/jobs"), get("/provider-health").catch(() => null)]).then(([j, health]) => {
@@ -1675,10 +1694,10 @@ function WorkersPanel({ ctx }) {
 		withLang
 	]);
 	(0, react.useEffect)(() => {
-		if (surface === CREW_UI_SURFACES.OFFICIAL) refreshHarnessModels();
+		if (surfaceResponsibilities(surface).fullControlPlane) refreshHarnessModels();
 	}, [surface, refreshHarnessModels]);
 	(0, react.useEffect)(() => {
-		if (surface === CREW_UI_SURFACES.OFFICIAL) refreshProviderInventory();
+		if (surfaceResponsibilities(surface).fullControlPlane) refreshProviderInventory();
 	}, [surface, refreshProviderInventory]);
 	const act = (0, react.useCallback)(async (target, confirmName) => {
 		if (confirmName && !window.confirm(copy.confirmRestore(confirmName))) return;
@@ -1721,6 +1740,34 @@ function WorkersPanel({ ctx }) {
 		get,
 		copy
 	]);
+	/** Request a Crew 3210 restart through the durable supervisor channel
+	*  (hub writes the request; the Windows watcher executes it). Polls until
+	*  VERIFIED or a terminal failure. Same-origin against the 3210 API — the
+	*  legacy 3080 supervisor endpoint is retired. */
+	const requestRestart = (0, react.useCallback)(async (reason) => {
+		const created = await post("/runtime/restart-request", {
+			confirm: true,
+			reason: reason ?? "configuration change"
+		});
+		if (!created.ok) throw new Error(created.code ?? created.error ?? copy.providerLifecycleError);
+		const requestId = created.request_id;
+		const deadline = Date.now() + 9e4;
+		for (;;) {
+			await new Promise((resolve) => setTimeout(resolve, 1e3));
+			if (Date.now() > deadline) throw new Error("Crew restart timed out");
+			const status = await get(`/runtime/restart-status?id=${encodeURIComponent(requestId)}`);
+			if (!status.ok) continue;
+			if (status.state === "VERIFIED") return {
+				ok: true,
+				...status
+			};
+			if (status.state !== "RESTART_REQUESTED") throw new Error(status.state ?? "Crew restart failed");
+		}
+	}, [
+		post,
+		get,
+		copy
+	]);
 	/** Selects & checkboxes: apply immediately. */
 	const field = (key, value) => {
 		setConfig((c) => ({
@@ -2020,13 +2067,7 @@ function WorkersPanel({ ctx }) {
 			}), path);
 			if (!result.ok) throw new Error(result.code ?? result.error ?? copy.providerLifecycleError);
 			if (result.restart_required === true && result.result?.state === "RESTART_PENDING") {
-				const restartPath = "http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart";
-				const restarted = await readJson(await fetch(restartPath, {
-					method: "POST",
-					headers: { "content-type": "application/json" },
-					body: JSON.stringify({ confirm: true })
-				}), restartPath);
-				if (!restarted.ok) throw new Error(restarted.code ?? restarted.error ?? copy.providerLifecycleError);
+				await requestRestart("provider delete");
 				const verified = await post(`/providers/${encoded}/verify-delete`, {
 					transaction_id: planned.plan.plan_id,
 					confirm: true
@@ -2065,13 +2106,7 @@ function WorkersPanel({ ctx }) {
 			});
 			if (!result.ok) throw new Error(result.code ?? result.error ?? copy.providerLifecycleError);
 			if (result.restart_required === true && result.result?.state === "RESTART_PENDING") {
-				const restartPath = "http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart";
-				const restarted = await readJson(await fetch(restartPath, {
-					method: "POST",
-					headers: { "content-type": "application/json" },
-					body: JSON.stringify({ confirm: true })
-				}), restartPath);
-				if (!restarted.ok) throw new Error(restarted.code ?? restarted.error ?? copy.providerLifecycleError);
+				await requestRestart("provider migrate");
 				const verified = await post(`/providers/${encoded}/verify-migration`, {
 					transaction_id: planned.plan.plan_id,
 					confirm: true
@@ -2100,15 +2135,7 @@ function WorkersPanel({ ctx }) {
 				confirm: true
 			});
 			if (!result.ok) throw new Error(result.code ?? result.error ?? copy.providerLifecycleError);
-			if (result.restart_required === true) {
-				const restartPath = "http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart";
-				const restarted = await readJson(await fetch(restartPath, {
-					method: "POST",
-					headers: { "content-type": "application/json" },
-					body: JSON.stringify({ confirm: true })
-				}), restartPath);
-				if (!restarted.ok) throw new Error(restarted.code ?? restarted.error ?? copy.providerLifecycleError);
-			}
+			if (result.restart_required === true) await requestRestart("provider migrate");
 			setNotice(copy.saved);
 			await refreshProviderInventory();
 		} catch (error) {
@@ -2153,13 +2180,7 @@ function WorkersPanel({ ctx }) {
 			});
 			if (!result.ok) throw new Error(result.code ?? result.error ?? copy.providerLifecycleError);
 			if (result.restart_required === true && result.state === "ROLLBACK_PENDING") {
-				const restartPath = "http://127.0.0.1:3080/_dsh/dsh-crew/supervisor/restart";
-				const restarted = await readJson(await fetch(restartPath, {
-					method: "POST",
-					headers: { "content-type": "application/json" },
-					body: JSON.stringify({ confirm: true })
-				}), restartPath);
-				if (!restarted.ok) throw new Error(restarted.code ?? restarted.error ?? copy.providerLifecycleError);
+				await requestRestart("provider migrate");
 				const verified = await post(`/providers/${encoded}/verify-rollback`, {
 					transaction_id: transactionId,
 					confirm: true
@@ -4754,7 +4775,7 @@ function WorkersPanel({ ctx }) {
 }
 function apply$1(ctx) {
 	let runningCount = 0;
-	let officialSurface = null;
+	let badgeSurface = null;
 	ctx.slots.inject("settings.section", () => {
 		let dispose = register();
 		function register() {
@@ -4783,11 +4804,14 @@ function apply$1(ctx) {
 		const poll = async () => {
 			if (document.visibilityState !== "visible") return;
 			try {
-				if (officialSurface === null) {
-					const response = await fetch(`${API}/bridge-status`, { cache: "no-store" });
-					officialSurface = classifyCrewSurface({ bridgeStatus: response.ok ? await response.json() : null }) === CREW_UI_SURFACES.OFFICIAL;
+				if (badgeSurface === null) {
+					const [bridgeStatus, runtime] = await Promise.all([fetch(`${API}/bridge-status`, { cache: "no-store" }).then((r) => r.ok ? r.json() : null).catch(() => null), fetch(`${API}/runtime`, { cache: "no-store" }).then((r) => r.ok ? r.json() : null).catch(() => null)]);
+					badgeSurface = surfaceResponsibilities(classifyCrewSurface({
+						bridgeStatus,
+						runtime
+					})).fullControlPlane;
 				}
-				if (!officialSurface) return;
+				if (!badgeSurface) return;
 				const r = await (await fetch(`${API}/jobs`, { cache: "no-store" })).json();
 				const n = r.ok ? (r.jobs ?? []).filter((j) => j.status === "running").length : 0;
 				if (n !== runningCount) {