feat(web): add URL query param deep-linking for dashboard nodes

.gitignore

@@ -14,8 +14,8 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
+/lib/
+/lib64/
 parts/
 sdist/
 var/
@@ -80,3 +80,4 @@ Thumbs.db
 
 # Frontend
 src/conductor/web/frontend/node_modules/
+src/conductor/designer/frontend/node_modules/

src/conductor/cli/app.py

@@ -238,6 +238,17 @@ def run(
             help="Workflow inputs in name=value format. Can be repeated.",
         ),
     ] = None,
+    raw_metadata: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--metadata",
+            "-m",
+            help=(
+                "Workflow metadata in key=value format. "
+                "Merged on top of YAML metadata. Can be repeated."
+            ),
+        ),
+    ] = None,
     dry_run: Annotated[
         bool,
         typer.Option(
@@ -300,12 +311,14 @@ def run(
 
     Execute a multi-agent workflow defined in the specified YAML file.
     Workflow inputs can be provided using --input flags.
+    Metadata can be provided using --metadata flags (merged on top of YAML metadata).
 
     \b
     Examples:
         conductor run workflow.yaml
         conductor run workflow.yaml --input question="What is Python?"
         conductor run workflow.yaml -i question="Hello" -i context="Programming"
+        conductor run workflow.yaml --metadata tracker=ado -m work_item_id=1814
         conductor run workflow.yaml --provider copilot
         conductor run workflow.yaml --dry-run
         conductor run workflow.yaml --skip-gates
@@ -377,6 +390,11 @@ def run(
     # Also parse --input.name=value style from sys.argv
     inputs.update(InputCollector.extract_from_args())
 
+    # Parse --metadata key=value flags (separate from inputs)
+    cli_metadata: dict[str, str] = {}
+    if raw_metadata:
+        cli_metadata.update(parse_input_flags(raw_metadata))
+
     # Resolve log file path
     resolved_log_file: Path | None = None
     if log_file is not None:
@@ -398,6 +416,7 @@ def run(
                 log_file=resolved_log_file,
                 no_interactive=True,  # Always non-interactive in background
                 web_port=web_port,
+                metadata=cli_metadata,
             )
             console.print(f"[bold cyan]Dashboard:[/bold cyan] {url}")
             console.print(
@@ -422,6 +441,7 @@ def run(
                 web=web,
                 web_port=web_port,
                 web_bg=web_bg,
+                metadata=cli_metadata,
             )
         )
 
@@ -1045,3 +1065,61 @@ def update() -> None:
     except Exception as e:
         print_error(e)
         raise typer.Exit(code=1) from None
+
+
+@app.command()
+def designer(
+    workflow: Annotated[
+        str | None,
+        typer.Argument(
+            help="Optional workflow YAML file to open for editing.",
+        ),
+    ] = None,
+    port: Annotated[
+        int,
+        typer.Option(
+            "--port",
+            help="Port to run the designer server on (0 = auto-select).",
+        ),
+    ] = 0,
+    no_open: Annotated[
+        bool,
+        typer.Option(
+            "--no-open",
+            help="Don't auto-open the browser.",
+        ),
+    ] = False,
+    host: Annotated[
+        str,
+        typer.Option(
+            "--host",
+            help="Host to bind the server to.",
+        ),
+    ] = "127.0.0.1",
+) -> None:
+    """Launch the visual workflow designer.
+
+    Opens a web-based drag-and-drop editor for creating and editing
+    conductor workflow YAML files.
+
+    \b
+    Examples:
+        conductor designer                          # Create new workflow
+        conductor designer workflow.yaml            # Edit existing file
+        conductor designer --port 3000              # Use specific port
+        conductor designer workflow.yaml --no-open  # Don't open browser
+    """
+    from conductor.designer.cli import run_designer
+
+    try:
+        run_designer(
+            workflow_path=workflow,
+            host=host,
+            port=port,
+            no_open=no_open,
+        )
+    except KeyboardInterrupt:
+        console.print("\n[dim]Designer stopped.[/dim]")
+    except Exception as e:
+        print_error(e)
+        raise typer.Exit(code=1) from None

src/conductor/cli/bg_runner.py

@@ -62,6 +62,7 @@ def launch_background(
     log_file: Path | None = None,
     no_interactive: bool = True,
     web_port: int = 0,
+    metadata: dict[str, str] | None = None,
 ) -> str:
     """Fork a detached child process running the workflow with a web dashboard.
 
@@ -77,6 +78,7 @@ def launch_background(
         log_file: Optional log file path.
         no_interactive: Whether to disable interactive mode (always True for bg).
         web_port: Desired port (0 = auto-select).
+        metadata: Optional CLI metadata key=value pairs.
 
     Returns:
         The dashboard URL (e.g. ``http://127.0.0.1:8080``).
@@ -107,6 +109,11 @@ def launch_background(
     for key, value in inputs.items():
         cmd.extend(["--input", f"{key}={_serialize_value(value)}"])
 
+    # Forward metadata
+    if metadata:
+        for key, value in metadata.items():
+            cmd.extend(["--metadata", f"{key}={value}"])
+
     if provider_override:
         cmd.extend(["--provider", provider_override])
 

src/conductor/cli/pid.py

@@ -38,13 +38,21 @@ def pid_dir() -> Path:
     return d
 
 
-def write_pid_file(pid: int, port: int, workflow_path: str | Path) -> Path:
+def write_pid_file(
+    pid: int,
+    port: int,
+    workflow_path: str | Path,
+    run_id: str = "",
+    log_file: str = "",
+) -> Path:
     """Write a PID file for a background workflow process.
 
     Args:
         pid: Process ID of the background child.
         port: TCP port the web dashboard is listening on.
         workflow_path: Path to the workflow YAML file.
+        run_id: Unique run identifier (from event log subscriber).
+        log_file: Path to the JSONL event log file.
 
     Returns:
         Path to the created PID file.
@@ -58,6 +66,8 @@ def write_pid_file(pid: int, port: int, workflow_path: str | Path) -> Path:
         "port": port,
         "workflow": str(workflow_path),
         "started_at": datetime.now(UTC).isoformat(),
+        "run_id": run_id,
+        "log_file": log_file,
     }
 
     filepath.write_text(json.dumps(data, indent=2))

src/conductor/cli/run.py

@@ -990,6 +990,7 @@ async def run_workflow_async(
     web: bool = False,
     web_port: int = 0,
     web_bg: bool = False,
+    metadata: dict[str, str] | None = None,
 ) -> dict[str, Any]:
     """Execute a workflow asynchronously.
 
@@ -1003,6 +1004,7 @@ async def run_workflow_async(
         web: If True, start a real-time web dashboard.
         web_port: Port for the web dashboard (0 = auto-select).
         web_bg: If True, auto-shutdown dashboard after workflow + client disconnect.
+        metadata: Optional CLI metadata to merge on top of YAML-declared metadata.
 
     Returns:
         The workflow output as a dictionary.
@@ -1032,7 +1034,13 @@ async def run_workflow_async(
         from conductor.web.server import WebDashboard
 
         bg_mode = web_bg or os.environ.get("CONDUCTOR_WEB_BG") == "1"
-        dashboard = WebDashboard(emitter, host="127.0.0.1", port=web_port, bg=bg_mode)
+        dashboard = WebDashboard(
+            emitter,
+            host="127.0.0.1",
+            port=web_port,
+            bg=bg_mode,
+            workflow_root=Path(workflow_path).resolve().parent,
+        )
 
         try:
             await dashboard.start()
@@ -1054,6 +1062,10 @@ async def run_workflow_async(
         config = load_config(workflow_path)
         verbose_log_timing("Configuration loaded", time.time() - load_start)
 
+        # Merge CLI metadata on top of YAML-declared metadata
+        if metadata:
+            config.workflow.metadata.update(metadata)
+
         # Log workflow details
         verbose_log(f"Workflow: {config.workflow.name}")
         verbose_log(f"Entry point: {config.workflow.entry_point}")
@@ -1116,6 +1128,10 @@ async def run_workflow_async(
                 event_emitter=emitter,
                 keyboard_listener=listener,
                 web_dashboard=dashboard,
+                run_id=event_log_subscriber.run_id if event_log_subscriber else "",
+                log_file=str(event_log_subscriber.path) if event_log_subscriber else "",
+                dashboard_port=(dashboard._actual_port if dashboard is not None else None),
+                bg_mode=web_bg or os.environ.get("CONDUCTOR_WEB_BG") == "1",
             )
 
             # Share interrupt_event with dashboard so POST /api/stop can abort agents

src/conductor/cli/validate.py

@@ -40,7 +40,6 @@ def validate_workflow(
 
     try:
         config = load_config(workflow_path)
-        return True, config
     except ConductorError as e:
         # Display structured error
         display_validation_error(e, workflow_path, output_console)
@@ -56,6 +55,20 @@ def validate_workflow(
         )
         return False, None
 
+    # Semantic validation: cross-field references, template refs, etc.
+    try:
+        from conductor.config.validator import validate_workflow_config
+
+        warnings = validate_workflow_config(config, workflow_path=workflow_path)
+        if warnings:
+            for warning in warnings:
+                output_console.print(f"  [yellow]⚠[/yellow] {warning}")
+    except ConductorError as e:
+        display_validation_error(e, workflow_path, output_console)
+        return False, None
+
+    return True, config
+
 
 def display_validation_error(
     error: ConductorError,

src/conductor/config/schema.py

@@ -475,6 +475,36 @@ class AgentDef(BaseModel):
         workflow: ./research-pipeline.yaml
     """
 
+    input_mapping: dict[str, str] | None = None
+    """Optional mapping of sub-workflow input names to Jinja2 expressions.
+
+    Each key is a sub-workflow input parameter name. Each value is a Jinja2
+    template expression evaluated against the parent workflow's context.
+
+    When present, the rendered values are passed as the sub-workflow's inputs
+    instead of forwarding the parent's workflow.input.* values.
+
+    Only valid for type='workflow' agents.
+
+    Example::
+
+        input_mapping:
+          work_item_id: "{{ task_manager.output.current_issue_id }}"
+          title: "{{ task_manager.output.current_issue_title }}"
+    """
+
+    max_depth: int | None = Field(None, ge=1, le=10)
+    """Per-agent sub-workflow depth limit.
+
+    Overrides the global MAX_SUBWORKFLOW_DEPTH (10) with a tighter bound.
+    Only valid for type='workflow' agents. Useful for self-referential
+    workflows to set an explicit recursion limit.
+
+    Example::
+
+        max_depth: 3  # Allow at most 3 levels of recursion
+    """
+
     max_session_seconds: float | None = Field(None, ge=1.0)
     """Maximum wall-clock duration for this agent's session in seconds.
 
@@ -529,6 +559,10 @@ def validate_agent_type(self) -> AgentDef:
                 raise ValueError("human_gate agents require 'options'")
             if not self.prompt:
                 raise ValueError("human_gate agents require 'prompt'")
+            if self.input_mapping:
+                raise ValueError("human_gate agents cannot have 'input_mapping'")
+            if self.max_depth is not None:
+                raise ValueError("human_gate agents cannot have 'max_depth'")
         elif self.type == "script":
             if not self.command:
                 raise ValueError("script agents require 'command'")
@@ -555,6 +589,10 @@ def validate_agent_type(self) -> AgentDef:
                 raise ValueError("script agents cannot have 'max_agent_iterations'")
             if self.retry is not None:
                 raise ValueError("script agents cannot have 'retry'")
+            if self.input_mapping:
+                raise ValueError("script agents cannot have 'input_mapping'")
+            if self.max_depth is not None:
+                raise ValueError("script agents cannot have 'max_depth'")
         elif self.type == "workflow":
             if not self.workflow:
                 raise ValueError("workflow agents require 'workflow' path")
@@ -578,6 +616,18 @@ def validate_agent_type(self) -> AgentDef:
                 raise ValueError("workflow agents cannot have 'max_agent_iterations'")
             if self.retry is not None:
                 raise ValueError("workflow agents cannot have 'retry'")
+        else:
+            # Regular agent or human_gate — input_mapping is not valid
+            if self.input_mapping:
+                raise ValueError(
+                    f"'{self.type or 'agent'}' agents cannot have 'input_mapping' "
+                    "(only workflow agents support input_mapping)"
+                )
+            if self.max_depth is not None:
+                raise ValueError(
+                    f"'{self.type or 'agent'}' agents cannot have 'max_depth' "
+                    "(only workflow agents support max_depth)"
+                )
         return self
 
 
@@ -738,6 +788,13 @@ class WorkflowDef(BaseModel):
     hooks: HooksConfig | None = None
     """Lifecycle event hooks."""
 
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Arbitrary key-value metadata for external tooling (dashboards, trackers, etc.).
+
+    Included verbatim in the ``workflow_started`` event so downstream
+    consumers can use it for enrichment without parsing the YAML source.
+    """
+
 
 class WorkflowConfig(BaseModel):
     """Complete workflow configuration file."""