ace-overseer 0.15.5 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94c89137756a33173502e2c4fd33bccd546544e9f9f6b407a98a7e50b471145e
-  data.tar.gz: 905b9f9838c3de93b5713ac9981c6c8bacc3b45aeb5bcaab6158af1c87ccc042
+  metadata.gz: 9f1239c62289b213199cac3a316f72301a82477c6d688a70d991eea76880f2cc
+  data.tar.gz: 4b847ed09a40f56ad43fc52b74db62325230f8c2cd393f2a175491fe21fd262f
 SHA512:
-  metadata.gz: a0f8a6c0eb6ed7c5073b14abb8c89e927056cb6a350a9145a88f851ae364397cc86d3a886906b16efbfbc1be98b7e67da9570ef09348a3af72fbc6919a23da2e
-  data.tar.gz: 641a1c96465712f92cd307ee430381ffe54fe7051571c04e5350d6df27fd83d8b887cddf4749b2043500df0a21ee8a3fe6d7c1a59905697973cede81fcd7c84b
+  metadata.gz: 6babe8200aa8f1c2275218d038dc6764a1d64e2af1a252659a38f0445ffd1c8bacfd23be81ae62c99eb22b37be34577a30fa4dc1ec2532a8a995d0c4339b4518
+  data.tar.gz: 668e65a1f12a922b02f1884d1e51eaec6aaf3bfd8fe5647911b1731ce51d4070dab43e79a98069ae8b93ef9fb7c357d168bc05d9af905cd1bbaa070d91f15812

data/.ace-defaults/nav/protocols/wfi-sources/ace-overseer.yml

@@ -0,0 +1,13 @@
+---
+# WFI Sources Protocol Configuration for ace-overseer gem
+# This enables workflow discovery from the installed ace-overseer gem
+
+name: ace-overseer
+type: gem
+description: Overseer workflow instructions from ace-overseer gem
+priority: 10
+
+config:
+  relative_path: handbook/workflow-instructions
+  pattern: "*.wf.md"
+  enabled: true

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added an explicit Lab runtime adapter for listing projects and agents, preparing and dispatching Works, forwarding prompts over stdin, starting exact-head reviews, and stopping workers.
+
+### Changed
+- Kept tmux as the default runtime while allowing `work-on`, `status`, and dry-run `prune` to delegate through the system-owned `/usr/local/bin/lab` boundary.
+
+
+## [0.16.0] - 2026-09-20
+
+### Added
+- Shipped the overseer lifecycle workflow so `wfi://overseer` resolves for gem consumers: the gem now registers `.ace-defaults/nav/protocols/wfi-sources/ace-overseer.yml` (ace-hitl pattern) and ships real workflow instructions for `work-on`, `status`, and `prune` in `handbook/workflow-instructions/overseer.wf.md`, with prune-safety and status-truth executed-check contracts as first-class non-negotiable steps.
+- Added a packaging test proving the built gem ships both the workflow-instructions payload and the wfi source registration so a future gemspec glob change cannot silently drop them.
+
+## [0.15.6] - 2026-09-02
+
+### Technical
+- Included in the coordinated all-package patch release preparation for ACE monorepo review.
 ## [0.15.5] - 2026-08-12
 
 ### Technical

data/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1> ACE - Overseer </h1>
 
-  One command to provision a worktree, open a tmux window, and start working on a task.
+  One command surface for local tmux work and isolated Lab workers.
 
   <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
   <br><br>
@@ -20,6 +20,10 @@
 
 Starting task work means creating a worktree, opening a tmux window, and preparing an assignment - three manual steps before you even begin coding. ace-overseer collapses that into a single command, tracks what is running where, and cleans up finished worktrees so nothing lingers. You can jump straight to a focused worktree any time with a single invocation.
 
+On a configured Lab machine, the same CLI can prepare and dispatch the Lab's
+system-owned `Work` objects. The default remains the existing tmux runtime;
+using Lab always requires an explicit `--runtime lab` or a Lab-only command.
+
 ## How It Works
 
 1. Resolve task refs and create a scoped worktree.
@@ -42,6 +46,22 @@ ace-overseer work-on --task 8q4 --preset work-on-task
 ace-overseer status --watch
 ```
 
+**Operate Lab workers** - prepare a reviewed Work, dispatch it to a configured
+agent, and inspect it without teaching ACE how to manage containers or Herdr:
+
+```bash
+ace-overseer prepare --runtime lab --project nervus \
+  --source lab-plan:oauth-callback --work W142 \
+  --planner admin-agy --title "OAuth callback validation"
+ace-overseer work-on --runtime lab --work W142 --agent builder-codex
+ace-overseer status --runtime lab --project nervus
+```
+
+Lab owns worktrees, credentials, Podman, and Herdr. Overseer decides what to
+run and delegates only through the absolute `/usr/local/bin/lab` boundary.
+Use `ace-overseer prune WORK... --runtime lab --dry-run` to preview exact Work
+destruction, then repeat with `--yes` to delegate it to Lab.
+
 **Clean up finished work** - [`ace-overseer prune`](docs/usage.md#ace-overseer-prune) removes completed worktrees safely. It checks three conditions before removing: assignment completed, task marked done, and git working tree clean. Use `--dry-run` to preview what would be pruned, `--force` for worktrees that fail safety checks, or `--assignment` to prune a single stale assignment.
 
 **Customize the workflow** - the full pipeline is defined in two layers: the [assignment preset](../ace-assign/.ace-defaults/assign/presets/work-on-task.yml) controls which steps run and in what order (onboard, implement, test, release, review, PR), while each step references a [workflow instruction](../ace-task/handbook/workflow-instructions/task/work.wf.md) that defines how it executes. Browse [available presets](../ace-assign/.ace-defaults/assign/presets/) or create your own to tailor the pipeline to your project.

data/docs/usage.md

@@ -3,8 +3,8 @@ doc-type: user
 title: ace-overseer Usage
 purpose: Full CLI reference for ace-overseer commands and options.
 ace-docs:
-  last-updated: 2026-03-22
-  last-checked: 2026-03-22
+  last-updated: 2026-08-30
+  last-checked: 2026-08-30
 ---
 
 # Usage
@@ -14,6 +14,12 @@ ace-docs:
 - `ace-overseer work-on`
 - `ace-overseer status`
 - `ace-overseer prune`
+- `ace-overseer projects`
+- `ace-overseer agents`
+- `ace-overseer prepare`
+- `ace-overseer prompt`
+- `ace-overseer review`
+- `ace-overseer stop`
 
 ## `ace-overseer work-on`
 
@@ -23,8 +29,11 @@ Invocation: `ace-overseer work-on --task <task-ref>`.
 
 Options:
 
-- `--task`, `-t` (required): task reference(s); repeatable and comma-separated values supported
+- `--task`, `-t` (required for tmux): task reference(s); repeatable and comma-separated values supported
 - `--preset`, `-p`: assignment preset name
+- `--runtime`: `tmux` (default) or `lab`
+- `--work`: existing Lab Work ID; required with `--runtime lab`
+- `--agent`: configured Lab agent ID; required with `--runtime lab`
 - `--quiet`, `-q`: suppress non-essential output
 - `--debug`, `-d`: show debug output
 - `--help`, `-h`: show help
@@ -41,6 +50,8 @@ Options:
 
 - `--format`: output format (`table`, `json`)
 - `--watch`, `-w`: auto-refresh dashboard
+- `--runtime`: `tmux` (default) or `lab`
+- `--project`: filter Lab Works by project
 - `--quiet`, `-q`: suppress non-essential output
 - `--debug`, `-d`: show debug output
 - `--help`, `-h`: show help
@@ -61,6 +72,7 @@ Options:
 - `--force`, `-f`: force-remove unsafe worktrees
 - `--yes`, `-y`: skip interactive confirmation
 - `--dry-run`: list prune candidates only
+- `--runtime`: `tmux` (default) or `lab`; Lab accepts dry-run only and delegates destruction to the exact `lab work destroy WORK --confirm` command
 - `--quiet`, `-q`: suppress non-essential output
 - `--debug`, `-d`: show debug output
 - `--help`, `-h`: show help
@@ -73,6 +85,32 @@ Check dashboard: `ace-overseer status`.
 
 Preview then prune: `ace-overseer prune --dry-run`, then `ace-overseer prune --yes`.
 
+## Lab Runtime
+
+Lab commands are available only where `/usr/local/bin/lab` is installed. ACE
+does not read Lab credentials and does not call Podman or Herdr directly.
+
+- `ace-overseer projects`: list registered Lab projects.
+- `ace-overseer agents`: list registered Lab agents and concurrency limits.
+- `ace-overseer prepare --runtime lab --project PROJECT --source KIND:ID --work WORK --planner AGENT --title TITLE`: create a reviewed Work and its isolated worktree.
+- `ace-overseer work-on --runtime lab --work WORK --agent AGENT`: reserve the agent, create or reuse its Herdr workspace, and dispatch it.
+- `ace-overseer status --runtime lab [--project PROJECT] [--format table|json]`: show Lab Work state. Continuous status lives in each project Herdr session, so `--watch` is intentionally rejected for Lab.
+- `ace-overseer prompt --work WORK --file PATH`: forward prompt text from a file to the Work pane. Piped stdin is also supported; prompt text is never passed as a process argument.
+- `ace-overseer review --work WORK --pr NUMBER`: prepare an exact-head admin review checkout and pane.
+- `ace-overseer stop --work WORK`: stop the assigned process without destroying Work state.
+- `ace-overseer prune WORK... --runtime lab --dry-run`: preview exact Work destruction commands; rerun with `--yes` to delegate each destruction to Lab.
+
+Example:
+
+```bash
+ace-overseer prepare --runtime lab --project nervus \
+  --source nervus-thread:67611c0b-f44c-4ac4-ae4e-55773b175617 \
+  --work W321 --planner admin-agy --title "Reviewed task title"
+ace-overseer work-on --runtime lab --work W321 --agent builder-codex
+ace-overseer prompt --work W321 --file .ace-local/prompts/W321.md
+ace-overseer status --runtime lab --project nervus --format json
+```
+
 ## Public Verification Paths
 
 Use these user-visible checks when validating behavior end-to-end:

data/handbook/workflow-instructions/overseer.wf.md

@@ -1,16 +1,126 @@
 ---
+name: overseer-workflow
+description: Orchestrate task worktrees with ace-overseer (work-on, status, prune) under binding prune-safety and status-truth executed-check contracts
+allowed-tools: Bash, Read
 doc-type: workflow
 title: Overseer Workflow
-purpose: overseer workflow
+purpose: Binding process contract for the overseer lifecycle (work-on, status, prune) with executed-check contracts for prune safety and status truth.
 ace-docs:
-  last-updated: 2026-03-12
-  last-checked: 2026-03-21
+  last-updated: '2026-09-20'
+  last-checked: '2026-09-20'
 ---
 
 # Overseer Workflow
 
+## Goal
+
+Orchestrate task worktrees with `ace-overseer` (work-on, status, prune) as the
+binding process contract. Two executed-check contracts in this workflow are
+non-negotiable: **prune safety** and **status truth**. They exist because a
+described or remembered check is how worktrees and commits get silently
+destroyed and stale blockers masquerade as state. Every step below is executed,
+never assumed.
+
 ## Instructions
 
-1. For work-on flows, run `ace-overseer work-on --task $ARGUMENTS`.
-2. Use `ace-overseer status` to inspect active worktrees.
-3. Use `ace-overseer prune --dry-run` before destructive cleanup, then `ace-overseer prune --yes` when confirmed.
+Run the loaded workflow as the source of truth and execute it end-to-end
+instead of only summarizing it.
+
+### 1) Work-on: start focused task work
+
+Provision a worktree, open a tmux window, and prepare the assignment:
+
+```bash
+ace-overseer work-on --task <task-ref>
+```
+
+- Repeatable/comma-separated refs fan out into the same batch: `ace-overseer work-on --task 230 --task 231,232`
+- Optional preset: `ace-overseer work-on --task <task-ref> --preset <preset-name>`
+- After launch, switch to the tmux window and run `/ace-assign-drive`.
+- Lab runtime variant (reserved agent + Herdr workspace): `ace-overseer work-on --runtime lab --work <work-id> --agent <agent-id>` -- `--task`/`--preset` are not supported with the Lab runtime.
+
+Never improvise worktree provisioning by hand when `work-on` exists; ad-hoc
+worktrees bypass the assignment lifecycle that `status` and `prune` rely on.
+
+### 2) Status: inspect active worktrees
+
+```bash
+ace-overseer status                     # table dashboard
+ace-overseer status --format json       # machine-readable snapshot
+```
+
+Lab runtime: `ace-overseer status --runtime lab [--project <project>]` (no
+`--watch`; continuous status lives in each project Herdr session).
+
+#### Status truth (non-negotiable executed check)
+
+Recorded blockers are **claims, not state**. During any status review:
+
+1. For each pending owner-blocked task, look for an executable non-secret
+   check that can confirm or refute the blocker, and run it when one exists.
+2. Close or correct stale tasks **in the same change** -- do not accept a
+   recorded blocker as state and do not defer the correction to a later pass.
+3. Report what you executed (command + observed output) as the evidence for
+   each kept or closed blocker. A described or remembered check is never
+   sufficient.
+
+### 3) Prune: remove finished worktrees safely
+
+Always preview before destructive cleanup:
+
+```bash
+ace-overseer prune --dry-run
+```
+
+Then apply only when confirmed:
+
+```bash
+ace-overseer prune --yes
+```
+
+- Targeted: `ace-overseer prune <task-ref|folder>...` or `ace-overseer prune --assignment <assignment-id>`
+- Lab runtime: `ace-overseer prune <work-id>... --runtime lab --dry-run`, rerun with `--yes` to delegate each destruction to Lab.
+
+#### Prune safety (non-negotiable executed check)
+
+Prune/removal of a worktree or branch happens **only after an executed
+preservation proof** for every commit that would be removed:
+
+1. Prove the work is already merged into its base:
+
+   ```bash
+   git merge-base --is-ancestor <work-head> <base>
+   ```
+
+   Exit code 0 proves every commit on the work branch is contained in the base.
+
+2. If the work was migrated elsewhere (squash-merge, cherry-pick, hand-off),
+   prove the copy exists with a subject-level search in the successor
+   repository:
+
+   ```bash
+   git -C <successor-repo> log --all --grep "<subject>"
+   ```
+
+   The search must return the commit(s) carrying the work. No output means no
+   proof.
+
+3. A described or remembered proof is never sufficient -- run the command and
+   observe the result in this session.
+
+4. Any commit without a proven copy **blocks the prune** for that worktree.
+   Report the blocked candidate (ref, head SHA, missing proof) to the operator;
+   never silently drop it and never force past a failed proof.
+
+## Non-Negotiable Contracts Summary
+
+| Contract     | Claim                             | Executed proof                                                                                                                                                            |
+|--------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Prune safety | "The work is preserved"           | `git merge-base --is-ancestor <work-head> <base>` (rc=0), or `git -C <successor-repo> log --all --grep "<subject>"` returning the migrated commit                          |
+| Status truth | "The task is blocked on the owner" | An executable non-secret check run in this session; stale tasks closed/corrected in the same change                                                                       |
+
+## Success Criteria
+
+- Work starts only through `ace-overseer work-on` (or the Lab-runtime equivalent), never through ad-hoc manual worktree provisioning.
+- Every status review re-verified pending owner-blocked tasks with an executed check and corrected stale state in the same change.
+- Every pruned worktree/branch had an executed preservation proof; candidates without proof were reported as blocked, not removed.

data/lib/ace/overseer/cli/commands/agents.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require "json"
+module Ace
+  module Overseer
+    module CLI
+      module Commands
+        class Agents < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          desc "List configured Lab agents"
+          def initialize(client: nil)
+            super()
+            @client = client || Molecules::LabClient.new
+          end
+          def call(**)
+            puts JSON.pretty_generate(@client.call("agents", "--json"))
+          rescue => error
+            raise Ace::Support::Cli::Error.new(error.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/cli/commands/prepare.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+module Ace
+  module Overseer
+    module CLI
+      module Commands
+        class Prepare < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          desc "Prepare a Work through the Lab runtime"
+          option :runtime, required: true, desc: "Runtime (lab)"
+          option :project, required: true, desc: "Lab project slug"
+          option :source, required: true, desc: "Source KIND:ID"
+          option :work, required: true, desc: "Work ID"
+          option :planner, required: true, desc: "Planner agent ID"
+          option :title, required: true, desc: "Reviewed Work title"
+          def initialize(client: nil)
+            super()
+            @client = client || Molecules::LabClient.new
+          end
+          def call(runtime:, project:, source:, work:, planner:, title:, **)
+            raise Ace::Support::Cli::Error, "unsupported runtime: #{runtime}" unless runtime == "lab"
+            puts @client.call(
+              "work", "prepare", project,
+              "--source", source,
+              "--work", work,
+              "--planner", planner,
+              "--title", title,
+              json: false
+            )
+          rescue Ace::Support::Cli::Error
+            raise
+          rescue => error
+            raise Ace::Support::Cli::Error.new(error.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/cli/commands/projects.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require "json"
+module Ace
+  module Overseer
+    module CLI
+      module Commands
+        class Projects < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          desc "List configured Lab projects"
+          def initialize(client: nil)
+            super()
+            @client = client || Molecules::LabClient.new
+          end
+          def call(**)
+            puts JSON.pretty_generate(@client.call("project", "list", "--json"))
+          rescue => error
+            raise Ace::Support::Cli::Error.new(error.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/cli/commands/prompt.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Ace
+  module Overseer
+    module CLI
+      module Commands
+        class Prompt < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          desc "Prompt a running Lab Work from stdin"
+          option :work, required: true, desc: "Work ID"
+          option :file, desc: "Read prompt text from a file instead of stdin"
+          def initialize(client: nil, input: $stdin)
+            super()
+            @client = client || Molecules::LabClient.new
+            @input = input
+          end
+          def call(work:, file: nil, **)
+            if file
+              prompt = File.read(file)
+            else
+              if @input.respond_to?(:tty?) && @input.tty?
+                raise Ace::Support::Cli::Error, "prompt text is required via --file or stdin"
+              end
+              prompt = @input.read
+            end
+            raise Ace::Support::Cli::Error, "prompt text must contain non-whitespace characters" if prompt.strip.empty?
+
+            puts @client.call("work", "prompt", work, stdin_data: prompt, json: false)
+          rescue => error
+            raise Ace::Support::Cli::Error.new(error.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/cli/commands/prune.rb

@@ -17,15 +17,24 @@ module Ace
           option :dry_run, type: :boolean, default: false, desc: "Show candidates only"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
+          option :runtime, default: "tmux", desc: "Runtime (tmux, lab)"
 
-          def initialize(orchestrator: nil, input: $stdin, output: $stdout)
+          def initialize(orchestrator: nil, input: $stdin, output: $stdout, lab_client: nil)
             super()
             @orchestrator = orchestrator || Organisms::PruneOrchestrator.new
             @input = input
             @output = output
+            @lab_client = lab_client || Molecules::LabClient.new
           end
 
           def call(**options)
+            runtime = options.fetch(:runtime, "tmux")
+            if runtime == "lab"
+              prune_lab(**options)
+              return
+            end
+            raise Ace::Support::Cli::Error, "unsupported runtime: #{runtime}" unless runtime == "tmux"
+
             Atoms::RepoGuard.ensure_repo!
 
             targets = Array(options[:targets] || [])
@@ -65,6 +74,28 @@ module Ace
 
           private
 
+          def prune_lab(**options)
+            raise Ace::Support::Cli::Error, "--assignment is not supported with Lab runtime; provide exact Work IDs" if options[:assignment]
+            raise Ace::Support::Cli::Error, "--force is not supported with Lab runtime" if options[:force]
+
+            works = Array(options[:targets]).map(&:to_s)
+            raise Ace::Support::Cli::Error, "provide at least one exact Lab Work ID to prune" if works.empty?
+
+            if options[:dry_run]
+              return if options[:quiet]
+
+              works.each { |work| puts "Would destroy Lab Work #{work}: /usr/local/bin/lab work destroy #{work} --confirm" }
+              return
+            end
+
+            raise Ace::Support::Cli::Error, "Lab prune requires --yes after reviewing --dry-run" unless options[:yes]
+
+            works.each do |work|
+              result = @lab_client.call("work", "destroy", work, "--confirm", json: false)
+              puts result unless options[:quiet]
+            end
+          end
+
           def print_assignment_result(result)
             candidate = result[:assignment_candidate]
             if result[:dry_run]

data/lib/ace/overseer/cli/commands/review.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+module Ace
+  module Overseer
+    module CLI
+      module Commands
+        class Review < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          desc "Start an exact-head Lab review"
+          option :work, required: true, desc: "Work ID"
+          option :pr, required: true, type: :integer, desc: "Forgejo PR number"
+          def initialize(client: nil)
+            super()
+            @client = client || Molecules::LabClient.new
+          end
+          def call(work:, pr:, **)
+            puts @client.call("work", "review", work, "--pr", pr, json: false)
+          rescue => error
+            raise Ace::Support::Cli::Error.new(error.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/cli/commands/status.rb

@@ -15,14 +15,30 @@ module Ace
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
           option :watch, aliases: ["-w"], type: :boolean, default: false, desc: "Auto-refresh dashboard"
+          option :runtime, default: "tmux", desc: "Runtime (tmux, lab)"
+          option :project, desc: "Filter Lab status by project"
 
-          def initialize(collector: nil, config: nil)
+          def initialize(collector: nil, config: nil, lab_client: nil)
             super()
             @collector = collector || Organisms::StatusCollector.new
             @config = config
+            @lab_client = lab_client || Molecules::LabClient.new
           end
 
-          def call(format:, **options)
+          def call(format:, runtime: "tmux", project: nil, **options)
+            if runtime == "lab"
+              if options[:watch]
+                raise Ace::Support::Cli::Error, "Lab watch runs in the project Herdr status pane; omit --watch"
+              end
+              arguments = ["work", "status"]
+              arguments.concat(["--project", project]) unless project.to_s.empty?
+              arguments << "--json" if format == "json"
+              output = @lab_client.call(*arguments, json: false)
+              puts output unless options[:quiet]
+              return
+            end
+            raise Ace::Support::Cli::Error, "unsupported runtime: #{runtime}" unless runtime == "tmux"
+
             Atoms::RepoGuard.ensure_repo!
             return if options[:quiet]
 

data/lib/ace/overseer/cli/commands/stop.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module Ace
+  module Overseer
+    module CLI
+      module Commands
+        class Stop < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          desc "Stop a Lab Work"
+          option :work, required: true, desc: "Work ID"
+          def initialize(client: nil)
+            super()
+            @client = client || Molecules::LabClient.new
+          end
+          def call(work:, **)
+            puts @client.call("work", "stop", work, json: false)
+          rescue => error
+            raise Ace::Support::Cli::Error.new(error.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/cli/commands/work_on.rb

@@ -9,18 +9,34 @@ module Ace
 
           desc "Create worktree, open tmux window, and prepare assignment"
 
-          option :task, aliases: ["-t"], type: :array, required: true,
+          option :task, aliases: ["-t"], type: :array,
             desc: "Task reference(s), repeatable and comma-separated (e.g., 230 --task 231,232)"
           option :preset, aliases: ["-p"], desc: "Assignment preset name"
+          option :runtime, default: "tmux", desc: "Runtime (tmux, lab)"
+          option :work, desc: "Existing Lab Work ID"
+          option :agent, desc: "Configured Lab agent ID"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
 
-          def initialize(orchestrator: nil)
+          def initialize(orchestrator: nil, lab_client: nil)
             super()
             @orchestrator = orchestrator || Organisms::WorkOnOrchestrator.new
+            @lab_client = lab_client || Molecules::LabClient.new
           end
 
-          def call(task: nil, preset: nil, **options)
+          def call(task: nil, preset: nil, runtime: "tmux", work: nil, agent: nil, **options)
+            if runtime == "lab"
+              if task || preset
+                raise Ace::Support::Cli::Error, "--task and --preset are not supported with Lab runtime"
+              end
+              raise Ace::Support::Cli::Error, "--work and --agent are required for Lab runtime" if work.to_s.empty? || agent.to_s.empty?
+
+              output = @lab_client.call("work", "dispatch", work, "--agent", agent, json: false)
+              puts output unless options[:quiet]
+              return
+            end
+            raise Ace::Support::Cli::Error, "unsupported runtime: #{runtime}" unless runtime == "tmux"
+
             Atoms::RepoGuard.ensure_repo!
 
             task_refs = normalize_task_refs(task)

data/lib/ace/overseer/cli.rb

@@ -5,6 +5,12 @@ require "ace/core"
 require_relative "cli/commands/work_on"
 require_relative "cli/commands/status"
 require_relative "cli/commands/prune"
+require_relative "cli/commands/projects"
+require_relative "cli/commands/agents"
+require_relative "cli/commands/prepare"
+require_relative "cli/commands/prompt"
+require_relative "cli/commands/review"
+require_relative "cli/commands/stop"
 
 module Ace
   module Overseer
@@ -16,7 +22,13 @@ module Ace
       REGISTERED_COMMANDS = [
         ["work-on", "Work on a task in isolated worktree"],
         ["status", "Show status of task worktrees"],
-        ["prune", "Remove stale task worktrees"]
+        ["prune", "Remove stale task worktrees"],
+        ["projects", "List configured Lab projects"],
+        ["agents", "List configured Lab agents"],
+        ["prepare", "Prepare a Lab Work"],
+        ["prompt", "Prompt a Lab Work from stdin"],
+        ["review", "Start a Lab Work review"],
+        ["stop", "Stop a Lab Work"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -28,6 +40,12 @@ module Ace
       register "work-on", Commands::WorkOn
       register "status", Commands::Status
       register "prune", Commands::Prune
+      register "projects", Commands::Projects
+      register "agents", Commands::Agents
+      register "prepare", Commands::Prepare
+      register "prompt", Commands::Prompt
+      register "review", Commands::Review
+      register "stop", Commands::Stop
 
       version_cmd = Ace::Support::Cli::VersionCommand.build(
         gem_name: "ace-overseer",

data/lib/ace/overseer/molecules/lab_client.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Ace
+  module Overseer
+    module Molecules
+      class LabClient
+        BINARY = "/usr/local/bin/lab"
+
+        def initialize(runner: Open3)
+          @runner = runner
+        end
+
+        def call(*arguments, stdin_data: nil, json: true)
+          stdout, stderr, status = @runner.capture3(
+            BINARY,
+            *arguments.map(&:to_s),
+            stdin_data: stdin_data.to_s
+          )
+          raise Error, stderr.to_s.strip.empty? ? "Lab command failed" : stderr.to_s.strip unless status.success?
+
+          return stdout unless json
+
+          JSON.parse(stdout)
+        rescue Errno::ENOENT
+          raise Error, "Lab runtime unavailable: #{BINARY} is not installed"
+        rescue JSON::ParserError => error
+          raise Error, "Lab returned invalid JSON: #{error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/overseer/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Overseer
-    VERSION = "0.15.5"
+    VERSION = "0.16.0"
   end
 end

data/lib/ace/overseer.rb

@@ -16,6 +16,7 @@ require_relative "overseer/atoms/repo_guard"
 require_relative "overseer/atoms/preset_resolver"
 require_relative "overseer/atoms/status_formatter"
 require_relative "overseer/molecules/worktree_provisioner"
+require_relative "overseer/molecules/lab_client"
 require_relative "overseer/molecules/tmux_window_opener"
 require_relative "overseer/molecules/assignment_launcher"
 require_relative "overseer/molecules/worktree_context_collector"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-overseer
 version: !ruby/object:Gem::Version
-  version: 0.15.5
+  version: 0.16.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: ace-support-fs
   requirement: !ruby/object:Gem::Requirement
@@ -71,42 +71,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.55'
+        version: '0.56'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.55'
+        version: '0.56'
 - !ruby/object:Gem::Dependency
   name: ace-git
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '0.23'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '0.23'
 - !ruby/object:Gem::Dependency
   name: ace-git-worktree
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.21'
+        version: '0.22'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.21'
+        version: '0.22'
 - !ruby/object:Gem::Dependency
   name: ace-task
   requirement: !ruby/object:Gem::Requirement
@@ -201,6 +201,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".ace-defaults/nav/protocols/skill-sources/ace-overseer.yml"
+- ".ace-defaults/nav/protocols/wfi-sources/ace-overseer.yml"
 - ".ace-defaults/overseer/config.yml"
 - CHANGELOG.md
 - LICENSE
@@ -221,14 +222,21 @@ files:
 - lib/ace/overseer/atoms/repo_guard.rb
 - lib/ace/overseer/atoms/status_formatter.rb
 - lib/ace/overseer/cli.rb
+- lib/ace/overseer/cli/commands/agents.rb
+- lib/ace/overseer/cli/commands/prepare.rb
+- lib/ace/overseer/cli/commands/projects.rb
+- lib/ace/overseer/cli/commands/prompt.rb
 - lib/ace/overseer/cli/commands/prune.rb
+- lib/ace/overseer/cli/commands/review.rb
 - lib/ace/overseer/cli/commands/status.rb
+- lib/ace/overseer/cli/commands/stop.rb
 - lib/ace/overseer/cli/commands/work_on.rb
 - lib/ace/overseer/models/assignment_prune_candidate.rb
 - lib/ace/overseer/models/prune_candidate.rb
 - lib/ace/overseer/models/work_context.rb
 - lib/ace/overseer/molecules/assignment_launcher.rb
 - lib/ace/overseer/molecules/assignment_prune_safety_checker.rb
+- lib/ace/overseer/molecules/lab_client.rb
 - lib/ace/overseer/molecules/prune_safety_checker.rb
 - lib/ace/overseer/molecules/tmux_window_opener.rb
 - lib/ace/overseer/molecules/worktree_context_collector.rb