Director Runs

Director runs let Workbench orchestrate Director books — structured, repeatable processes — as a primitive that sits alongside workspaces. Workbench owns the environment (directories, repos, skills); Director owns the process (the book). Workbench never interprets book contents: books are discovered, listed, and materialized generically.

Runs require the Director settings to be configured first — see Settings below.

Workspaces ↔ Runs toggle

The sidebar has a two-tab toggle at the top: Workspaces (the default) and Runs. The Runs view lists runs in two sections:

Current — runs that are creating, active, completing, or failed
History — completed runs, retained after their directories are cleaned up

Each row shows the run’s name, book, lifecycle type badge (Ephemeral / Durable), and status badge. Selecting a run opens its work area in the main pane; selecting a run and selecting a workspace are mutually exclusive.

Switching the toggle keeps the main pane in step with the visible mode. Each mode remembers the item that was open when you left it: clicking Runs reopens the last run you had open, and clicking Workspaces reopens the last workspace and its chat. If there is nothing to reopen — you left that mode from the dashboard, or the remembered run or workspace has since been deleted or archived — the main pane shows the dashboard. Opening a run or workspace from anywhere else (the command palette, a notification, the Work tab’s run status) switches the toggle to match. This memory lasts for the app session and is not persisted.

Run work area

Selecting a run opens a three-panel work area: the runs sidebar on the left, a center pane, and a right rail.

While the run is being created the center pane shows a spinner with “Setting up run environment…” — the tabs appear once the run becomes Active. While the run directory exists (status Active, Failed, or Completing), the center pane has four tabs:

Chat — the run’s built-in agent chat (see Run chat). While the agent is working, a step breadcrumb (e.g. “Phase 1/2 · Step 3/5 — node-name”) appears next to the processing spinner so you can see where the run is without switching to the Run tab. Progress auto-polls every 15 seconds.
Files — a read-only browser over the run directory: run/RUN.md, stage directories, artifacts, and the repo checkouts. Files open in a plain text view (truncated at 1 MB; binary files are not rendered).
Commands — a flat timeline of all agent tool calls made during the run, including calls from subagents. Each row represents a single tool invocation with timestamps and results. When detailed output is enabled (the extendedToolCallOutput setting), rows are expandable to show the full input and output for each tool call. The Commands tab is available while the run is active and remains accessible after the run is completed, providing a complete record of all work performed.
Run — Director’s own view of the process, from the director.status.v1 state report: the current cursor position (phase / step), a census of complete / skipped / blocked / unresolved nodes, any well-formedness violations, halted nodes with their reasons, and the full stage tree. The view renders the run/STATE.json Director last wrote; Refresh re-runs director status --write so the document is recomputed on the spot (this requires the Director binary setting).
Friction — the live FRICTION_LOG.md from the run root.

After teardown the tabs are replaced by the RESULT.md / FRICTION_LOG.md snapshots captured into history.

The right rail shows the run’s status, and — once Director has reported state — a Stages section (the top-level nodes of the run tree, with the current phase highlighted) and an Artifacts section (every artifact recorded by a stage’s closing record, with the stage that recorded it). Below those sit the run’s repositories with the shared run branch, and the lifecycle actions (Complete run, Cancel, Delete from history).

Remote access

When you pair another machine as owner (see the Remote features), the Runs sidebar also lists that machine’s runs, grouped under the connection’s name. Selecting a remote run opens the same work area — the Files, Run, and Friction tabs (including Refresh on the Run tab) all read from the machine that owns the run. Configuration errors name that machine: fix them in Settings > Director there — Director settings are never editable over a remote connection.

Remote runs are visible to owner connections only; scoped shares never see runs. A remote owner can Complete (teardown) and Delete a run on the connected machine: the teardown (branch push, cleanup, snapshot) runs on the server and live status updates stream to your desktop as the run transitions to Completing and then Completed or Failed.

Creating a run works remotely too: each connected machine’s runs group in the sidebar has its own New run button, and a wizard launched from that group reads that machine’s books and repositories, runs its pre-flight there, and creates the run on it. The target is fixed when the wizard opens. If the server’s Director settings are missing, the wizard shows an error naming that machine — fix it in Settings > Director on the server.

Run chat is also available for remote runs over owner connections. An owner can send messages to a run on a connected machine and receive streaming responses, trigger interactive prompts (questions, plan approvals, permission approvals), and use Stop — all executing on the machine that owns the run. Chat history is automatically reloaded on reconnect.

Creating a run

The New run button opens a five-step wizard:

Book — pick from the books discovered in your configured books directory. A book is a folder containing a CONTEXT.md with YAML frontmatter (book:, optional modes: and inputs:); the page title and first paragraph become the display title and description.
Type — Ephemeral is the only type available today. Durable runs (long-lived, persisted between sessions) are planned.
Setup — name the run, pick a mode (if the book declares modes), and fill in the book’s declared inputs. The step shows the run directory Workbench will create (<runs root>/<slug>) so inputs that take a path, such as a target repository, can be written relative to it — the path does not need to exist yet; a book step may create it.
Repositories — choose which of the target machine’s repositories to check out into the run.
Create — review the summary and create the run. Opening this step runs an environment pre-flight: devkit doctor --book <book> --json audits the tools the book declares (its CONTEXT.md frontmatter tools: key) and each tool is shown as pass / warn / fail with a message and, when something is wrong, a remedy. Create run is enabled only when no tool fails (warnings are allowed); fix the environment and use Re-check to audit again. If the book’s tool declaration is malformed or devkit cannot run, the error is shown in place of the report.

Book inputs

Books declare their inputs in CONTEXT.md frontmatter. Each input has a key, description, and an optional type. The wizard renders a different widget depending on the type:

Type	Widget	Behaviour
(none)	Text field	Free-form text input.
`path`	Text field + “Resolve in run directory” checkbox	When checked (the default), enter a name and Workbench joins it with the run root to produce an absolute path. Uncheck to enter a full absolute path manually. Path resolution is client-side — Workbench does not check whether the path exists.
`enum`	Dropdown	Populated from the book’s declared `options` list. The first option is selected by default.

The legacy input format (- target: description) is still accepted and renders as a plain text field.

Ephemeral run lifecycle

Creating an ephemeral run builds a temporary directory under your configured runs root:

The run directory is named from the run’s slug.
Each selected repository is checked out as a git worktree on a dedicated branch named run/<slug>-<run-id-prefix>, under a deterministic directory name (the repository’s slug — not the random workspace-style names).
Workbench seeds run/RUN.md with the book, mode, and inputs, then invokes director materialize and installs the book’s skills via skiller install.
A FRICTION_LOG.md is seeded in the run root for recording process friction during the run.

While the run is Active, work happens in the run directory — externally (terminals, editors) or through the run’s built-in chat (see below).

Completing a run (the Complete run action in the run panel, with an inline confirmation) tears it down:

Each repository checkout is verified clean — a dirty checkout fails the teardown so you never lose uncommitted work.
Each repo’s run branch is pushed to its default remote (repos without remotes are skipped). The pushed branch is the run’s result channel.
RESULT.md and FRICTION_LOG.md are snapshotted into the run’s database row.
Worktrees are removed and the run directory is deleted.

The run then moves to History with its snapshots viewable in the run panel. Teardown is resumable: if it fails partway (for example, a push fails), already-pushed repos are remembered and completing again picks up where it left off. Failed or cleaned-up runs can be removed from history with Delete from history.

Cancelling a run

If you want to discard a run without pushing branches or snapshotting artifacts, use the Cancel button in the run panel’s Lifecycle rail. Cancel is available for runs that are Active, Failed, or stuck in Creating. Cancelling removes the run’s worktrees and deletes the run directory immediately — no branches are pushed and no RESULT.md snapshot is taken. The run moves to Cancelled status and remains in history so you can see it was attempted; use Delete from history to remove it entirely.

Hosted runs (TODO plucks)

When you start a pluck from a workspace’s TODO list (using the Pluck modal or xp_work integration), Workbench automatically creates an ephemeral run inside the workspace’s worktree at .xp_work/<ITEM>/run/. This is a hosted run: it has no dedicated run directory of its own, but lives inside the workspace worktree as a sibling to the checked-out code.

The hosted run is created before the pluck message is sent, so the agent sees the run alongside the workspace from the start. The run’s state, progress, and friction log are visible in the Runs sidebar and in the run panel just like any ephemeral run. The agent works inside the workspace worktree, and chat stays in the workspace session — there is no separate run chat for hosted runs.

When you archive the workspace, Workbench automatically tears down the hosted run: it snapshots RESULT.md and FRICTION_LOG.md into the run history, removes the run directory, and marks the run as completed or failed depending on whether the pluck finished. A pluck that runs to completion moves its run into history where you can review the friction log and results after the workspace is gone.

Hosted runs require devkit skiller to be available in the workspace’s environment and the xp_work skill to be at version IMP-178 or later. If hosting fails (for example, if devkit is not found), the pluck proceeds as normal without creating a run, and the pluck’s progress is not tracked by Workbench.

Run chat

The run panel includes a chat with an agent working directly in the run’s root directory. Chat is available while the run is Active or Failed (so you can debug a failed run in place), and read-only during Completing; it disappears once the run directory is cleaned up. A session is created automatically the first time you open a run.

Ephemeral runs auto-start: once the run directory is materialized and the status moves to Active, the chat automatically sends an initial message instructing the agent to read RUN.md and begin work — you don’t need to type the first message yourself.

Run chat sessions are owned by the run, not by a workspace: they use the run directory as the working directory, and they are deleted along with the run when you Delete from history. Sending is blocked once a run has been cleaned up.

The run panel’s chat uses the same shared composer as workspace chat, providing:

Attachments: paste, drop, or pick files (truncated at 1 MB; binary files are not rendered).
Context-window meter: live token count for the current session history.
By-the-way messages (BTW): send notes without interrupting an in-flight turn.
Queued messages and steering: queue follow-ups to reply when the agent finishes; steer an in-flight turn by editing a queued message.
Slash commands: discovered from the run root (defined in SKIP_PATTERNS and inline Lua files), plus global commands.
Global pinned prompts: launch a pinned prompt as a new message.
Voice: record and transcribe audio messages.
Model, effort, and plan-mode toolbar: pick the model, reasoning effort, and plan-mode state before sending.

The run panel also includes a Terminal tab: one persistent shell per run, toggled via the composer button or Cmd+T (macOS) / Ctrl+T (Windows/Linux). The shell session persists across tab switches.

Interactive agent prompts (questions, plan approvals, permission approvals) work the same as in workspace chat.

Intentionally not supported in run chat:

Checkpoints and forking: the run directory has a single history; checkpoints and branching are deferred to a future phase.
Mid-turn steering and diff viewer: the Stop button ends the turn; a diff viewer for the run’s checkouts is not yet built.
SCM integration: PR/CI panels and branch management are not available for run checkouts.
Workspace-file attach and mentions: can reference run files, but not files from the workspace that owns the run.
Multi-tab terminals: one terminal per run; multiple terminals are not yet supported.
Available over owner connections only: scoped shares never see runs or run chat; chat requires an owner connection.

Run statuses

Status	Meaning
Creating	The run directory, checkouts, and materialization are in progress.
Active	The run is ready; work happens in the run directory.
Completing	Teardown (push + snapshot + delete) is in progress.
Completed	Torn down; snapshots retained in history.
Failed	Creation or teardown hit an error — shown in the run panel. Completing can be retried.
Cancelled	Discarded without pushing branches or snapshotting artifacts. Retained in history.

Settings

Configure Director under Settings > Director:

Setting	Description	Default
Director binary path	Absolute path to the `director` executable. Required.	—
Books directory	Directory containing Director books (folders with a `CONTEXT.md`). Required to list books in the wizard.	—
Runs root	Directory where ephemeral run directories are created. Required.	—
Skiller binary	Command or path used to install skills into a run.	`skiller`
DevKit binary	Command or path used for the New Run pre-flight audit.	`devkit`