From 0a0ca8e580fbbbbf58166b7269b86601c7f2008d Mon Sep 17 00:00:00 2001
From: "Tj (bougyman) Vanderpoel" <bougyman@users.noreply.github.com>
Date: Thu, 13 Aug 2026 16:45:29 -0400
Subject: [PATCH] feat: launch stokowski sessions via mix stokowski

Wires the existing workflow.yaml safety checks up to an actual launch:
uv run --project vendor/stokowski --extra web --with-editable
vendor/stokowski -- stokowski <workflow> <args...>.

--with-editable is required alongside --project - vendor/stokowski's
pyproject.toml has no [build-system] table, so a plain
uv run --project only syncs dependencies and never installs the
stokowski package/entry point itself (confirmed directly: fails with
"Failed to spawn: stokowski" otherwise, even though the venv builds
cleanly).

Verified end-to-end against the real workflow.yaml and a real
LINEAR_API_KEY - config validated, env-var fallback resolved
correctly, real Linear API call succeeded.

Closes #105
---
 lib/mix/tasks/stokowski.ex | 49 +++++++++++++++++++++++++++++---------
 1 file changed, 38 insertions(+), 11 deletions(-)

diff --git a/lib/mix/tasks/stokowski.ex b/lib/mix/tasks/stokowski.ex
index 9131906..a84925d 100644
--- a/lib/mix/tasks/stokowski.ex
+++ b/lib/mix/tasks/stokowski.ex
@@ -1,15 +1,26 @@
 defmodule Mix.Tasks.Stokowski do
-  @shortdoc "Validates this repo's workflow.yaml is safe for a Stokowski session"
+  @shortdoc "Starts a Stokowski agent-orchestration session against this repo's workflow.yaml"
 
   @moduledoc """
   #{@shortdoc}.
 
-      mix stokowski
+      mix stokowski [--dry-run] [--port PORT] [--host HOST] [-v]
 
-  Doesn't launch Stokowski itself yet - for now this just checks the
-  root `workflow.yaml` is safe to commit:
+  Checks the root `workflow.yaml` is safe (see below), then runs it via
+  `uv run --project vendor/stokowski`. `--with-editable` is required
+  alongside `--project` - `vendor/stokowski`'s `pyproject.toml` has no
+  `[build-system]` table, so a plain `uv run --project` only syncs its
+  dependencies, never installs the `stokowski` package/entry point
+  itself (confirmed directly - `uv run` without `--with-editable` fails
+  with "Failed to spawn: `stokowski`" even though the venv builds
+  cleanly). Fixing that upstream is a separate, future PR; this works
+  around it locally in the meantime. Any flags given are passed straight
+  through to `stokowski` itself; see `vendor/stokowski/README.md` for
+  what each does.
 
-    * it exists
+  Safety checks before launching:
+
+    * `workflow.yaml` exists
     * its `tracker.api_key`, if set at all, is a `"$VAR"` env-var
       reference rather than a bare literal key (omitting the key
       entirely is also fine - Stokowski then falls back to the
@@ -17,16 +28,17 @@ defmodule Mix.Tasks.Stokowski do
 
   `workflow.yaml` is meant to be tracked in this repo, not gitignored -
   this is a best-effort guard against a literal API key ever landing in
-  it, not a requirement that the file stay untracked.
-
-  See `vendor/stokowski/README.md` for what the file needs to contain;
-  actually starting a session is a follow-up step.
+  it, not a requirement that the file stay untracked. This task never
+  reads, passes, or logs that key itself - Stokowski resolves it on its
+  own and `uv run` inherits this process's environment unmodified.
   """
 
   use Mix.Task
 
+  alias RepoTasks.Shell
+
   @impl Mix.Task
-  def run(_argv) do
+  def run(argv) do
     workflow = Path.expand("workflow.yaml")
 
     unless File.exists?(workflow) do
@@ -48,7 +60,22 @@ defmodule Mix.Tasks.Stokowski do
         )
     end
 
-    Mix.shell().info("#{workflow} looks safe to use.")
+    Shell.run!(
+      "uv",
+      [
+        "run",
+        "--project",
+        "vendor/stokowski",
+        "--extra",
+        "web",
+        "--with-editable",
+        "vendor/stokowski",
+        "--",
+        "stokowski",
+        workflow
+      ] ++ argv
+    )
+
     :ok
   end