A turn is one full cycle from the user sending to the agent finishing a reply. A conversation has at most one in-flight turn. Parallelism is multiple conversations.

Terminal states

When a turn ends it enters exactly one of the following. The states are exclusive.

State	Meaning
Completed	The agent finished a normal reply
Failed	The agent reported an error
Cancelled	The user stopped the turn
Interrupted	The Host exited during the turn (crash, kill, restart)

Interrupted means the Host process disappeared. The agent may already have written files. Startup recovery marks leftover in-flight turns Interrupted so the conversation can accept a new turn. An interrupted turn is started again by the user.

Resume and rebind

Resume loads context into a newly started agent process. The in-progress token stream ends with the old process. Whether resume is available depends on capability bits the agent declared over ACP.

When loading the old agent session fails, confirmation may attach a new cold-start session (rebind). VibeX history stays. Hidden agent-side context starts empty. Handoff for the new process is written in the next message.

Fork

When the agent declares fork and an active session exists, fork copies visible history and agent-side context, then evolves independently. Otherwise the new conversation is a copy without hidden context. Fork starts from the current state.

Rollback to here on a user message truncates later generation so the user can edit and resend. Undo under a turn restores workspace files to the checkpoint taken before that message. The conversation record stays.

How-to: Turns: stop, resume, fork.

One in-flight at a time

While idle, the scheduler claims the next queued input and makes a new turn. Sends during an in-flight turn join the queue. Steering writes into the current in-flight turn. Cancel applies to that turn. Content already in the event log and files already written remain.

Handoff from orchestration

Delegated children, Workflow agent steps, and Automation single-session targets all create real turns. They reuse this chapter’s terminal states and the one-in-flight rule. Workflow pause cancels in-flight turns and continue opens a new turn. Automation recovery marks leftover direct turns Interrupted.

Conversation input splits into draft, queued input, steering, and permission response. Desktop, WebUI, companion, chat channels, and workflows share the same semantics. Authority is the conversation on the Host. Clients align by revision or event sequence.

Draft

A draft is unsubmitted Composer content belonging to that conversation. Authorized devices continue editing it. Each save carries a revision. On conflict the UI keeps the server version and the local version so the user can Keep server or Keep local. A successful turn submit with a matching revision clears the draft.

Queued input

Queued input is content the Host has accepted and not yet claimed into a new turn. While the conversation is idle, the scheduler turns items into turns in stable order. The queue survives refresh, device switch, and reconnect. Rows can be edited, reordered, or deleted.

A send while a turn is in flight joins the queue. A send while idle starts a new turn.

Steering

Steering is extra input on the in-flight turn. It belongs to that turn. Steering stays on the in-flight turn. When the agent declared the capability, the UI shows Steer this turn. When the agent lacks it, the field is hidden. Queued input remains a separate object.

Permission requests

A permission request is a gate inside a turn. File writes, shell, Git, and MCP tools pause on the timeline until Approve or Deny. Approving a write leaves commit and push in the Git panel. Remote and desktop answers resolve the same request, exclusively.

Opening a project folder and the built-in browser are done by the app. When the agent operates a page or clicks for the user, the timeline shows a separate permission request. See Permission prompts.

Consistency across entries

Desktop, WebUI, companion, and authorized chat channels see the same draft revision, the same queued input, and the same pending permission. After one person approves, other entries show the request resolved. Steering appended to a Workflow agent step follows the same turn or steer semantics as an ordinary conversation.

A project is an opened engineering directory. Conversations, workspaces, and the Git panel belong to that project. The project names “which codebase this is”. The workspace names “which tree this conversation reads and writes”.

How it opens

The desktop home offers Select Folder, Create New Project, and Clone Repository. A directory already recognized as a Git repository opens directly. A directory without .git is initialized on open or create. Clone pulls from a URL, then joins the project list.

A directory with .git can use the Git panel, branches, and worktrees. Paths shown on a remote client belong to the Host machine.

Relation to conversations

One project can hold many conversations. Kanban lists them per project. Opening a card switches the Workspace region to the tree bound to that conversation. Several conversations bound to the same root may overwrite one another’s uncommitted files. Isolation binds each conversation to its own worktree. See Conversation and workspace binding.

Deleting a project removes conversations and workspace data under it. Recent projects are stored on the client.

How-to: Open a project.

Paths and Host

A project path is a directory on the Host machine. Absolute paths in WebUI and on a workstation belong to that machine. Clone, create, and Git init also execute on the Host.

In this chapter, workspace means the execution container a conversation lands on: the project root, or a Git worktree cut from that root. The UI region named Workspace is documented in Workspace. The two words coexist in the product. They name different objects.

Project root

The root is the default landing tree. File, terminal, and Git use this tree until isolation is chosen. Several in-flight conversations bound to the root may write the same uncommitted files.

Worktree

A worktree is a Git working tree. Its path differs from the root. Repository objects are the same. Parallel tasks each bind a worktree so implementation and review use different working copies. Creating a worktree requires the project to already be a Git repository.

That conversation’s file tree, terminal, and Git operations point at this tree. A worktree-bound conversation shows Rebase and Rebase back above the execution pane: the former brings the target branch onto the current tree; the latter then merges the current tree back onto the target.

Delete is constrained by retention. Worktrees owned by a running turn or automation run are kept. After the conversation ends, merge, push, or publish finish in the Git panel.

Per-project post-create command, pre-destroy command, and count cap live in Settings → Worktrees. Global workspace directory and branch prefix live in Settings → Version control.

A workspace-less conversation uses a Host-assigned temp directory. See Workspace-less conversation.

Distinct UI senses

Workspace page under Settings → Appearance is the execution-region layout. Existing workspace / New workspace in the Create session dialog are this chapter’s directory or worktree. The Kanban workspace filter also means that tree. Follow the links in this reference for the intended object.

A conversation binds one workspace. Binding is chosen at create: an existing workspace, or a new Git worktree from the target branch. After bind, that conversation’s file tree, terminal, and Git all point at this tree.

Why one-to-one

A turn writes files. If one conversation mapped to two trees, permission requests, diffs, and timeline patches could not land in a single place. So one conversation binds one tree. Parallel work uses multiple conversations, each with its own bind.

Two conversations may bind the same root. Uncommitted files may overwrite each other. Isolation binds one of them to a worktree.

Lifecycle

Binding is set at create. Later the conversation can bind a worktree added afterwards. Follow-up merge and pull request happen in the Git panel. Automation and Workflow runs default to an independent worktree. Push stays a human step.

A workspace-less conversation has no bind of this kind. See Workspace-less conversation.

Choice at create

Existing workspace binds a root or worktree that already exists. New workspace creates a Git worktree from the target branch, then creates the conversation in that tree. A row marked will checkout first switches checkout before bind. A workspace-less conversation skips this step.

A workspace-less conversation belongs to no project. It is used for conceptual discussion or comparing approaches.

Turn rules, event log, resume, interrupt, draft, and queue match a regular conversation. Git panel and repository tree require a project workspace. Kanban lists project engineering tasks. Workspace-less conversations sit outside that list.

Tool root

The agent may still offer file and terminal tools. The tool root is a Host-assigned directory isolated per conversation. Relative paths resolve there. Absolute paths still follow the agent tool’s own resolution. The mode restricts the default tool root to that isolated directory. An OS sandbox is a different mechanism.

Event authority and the turn state machine match a regular conversation. Git panel and repository tree require Workspace membership.

The main UI splits into Kanban and Workspace. The previous chapter’s workspace is a directory or worktree. This chapter’s Workspace is the execution surface. The two senses of “workspace” coexist. They name different objects.

Responsibilities

Kanban shows parallel conversations in To Do, In Progress, To Review, and Done, and it opens session hub and usage stats. Workspace shows files, diff, terminal, and browser for the tree bound to the focused conversation. When implementation and review run together, look at both cards on Kanban, then open the review conversation to read the diff.

Conversation panels can be dragged side by side. The number of groups in a window is capped. Dragging only changes placement. Kanban still schedules. Workspace still lands.

Layout config

The two layouts are saved separately in Settings → Appearance → Page layout. The Kanban page arranges Session list, Session monitor, and Session execution. The Workspace page arranges Sidebar panels, Workspace, Sessions, and Terminal. A zone keeps its size when moved. Splitters on the page still resize widths.

Kanban lists parallel conversations by project and status. Each card is one conversation. Cards show status and jump into the execution pane.

Three pages

The four-column board uses To Do, In Progress, To Review, and Done. Dragging a card changes status. Clicking a card loads that conversation into the execution pane on the right.

Session hub splits the same work into Sessions, Session monitor, and Session execution. The monitor expands up to four live outputs. Usage stats shows token spend by project, conversation, and model, plus official subscription quota for some agents.

The product can surface about five conversation statuses at once. The list filters by workspace and coding agent, and it can archive, fork, and export Markdown / HTML. Delete skips sessions that are still running.

Relation to the event log

In-flight turns, waiting permissions, and Completed / Failed / Cancelled / Interrupted show on the card. The Kanban card, the UI panel, and the Host event log describe the same conversation. Rename happens on the conversation itself. Opening a card switches the Workspace region to the bound tree.

How-to: Board and many conversations.

Monitor and execution

Session monitor watches several outputs at once. After Move to execution area, input, permissions, and steering happen in the execution pane. Monitor itself only observes. The three zones can swap places in Settings → Appearance.

Workspace is the execution region in the UI. It shows the project root or worktree bound to the current conversation. Sidebar, editor, conversation column, and terminal column share the screen. That layout is saved on its own under Settings → Appearance.

Files and preview

The file tree expands from that workspace root. Common text and code can preview or edit. Very large or unknown types may be read-only. Diff is the check after a write is approved and before commit. Timeline patches point at paths on this tree. Uncommitted edits for a worktree-bound conversation stay on that tree.

High-fidelity .docx / .xlsx / .pptx preview comes from the official VibeX Office plugin. Opening those files starts a read-only preview process.

Git, terminal, browser

The Git panel offers stage, commit, branch, stash, and pull request. Merge and push are human steps. The terminal cwd matches this tree. After permission, the agent may operate the built-in browser. New tab can open Browser, Review, Note, or Terminal.

Paths in WebUI belong to the Host machine. Terminal and preview on a remote workstation also execute on the Host. Output returns over the remote protocol.

Relation to the workspace directory

The Workspace UI always points at the tree bound to the focused conversation. Switching cards switches file tree, Git state, and terminal cwd. Two worktrees can exist under one project. The UI shows one of them at a time.

A conversation panel is the Dock view that presents one conversation in a server-bound window. The conversation opens on the right by default. It can be dragged into the editor area, into a tab group, or into a left-right or top-bottom split. The number of conversation groups in a window is capped, matching the editor group cap.

One panel, one conversation

Each panel has its own event subscription, scroll position, draft view, and in-flight turn. Splits stop at the panel. Inside one window a conversation maps to one panel. Opening it again focuses that panel. Closing a panel only changes layout. An in-flight turn continues. The agent session stays. The conversation record stays.

Layout and draft

Layout is stored on the client, isolated by Host, project, and window. Another client machine needs its panels arranged again.

Drafts belong to the conversation on the Server. Authorized desktop, browser, and Android clients continue editing them. Saves carry a revision. Conflict keeps both versions. See Input control.

Fork and export

Fork on the session list creates a new conversation and a new panel. Export as Markdown or HTML reads the current projection. The event log stays. Delete skips rows that are still running.

Multi-agent collaboration in the product splits into delegation and Graph Workflow. Automation only triggers. Split logic belongs to delegation or the graph.

Delegation

Delegation is the parent agent handing work to another agent in the dialogue. The child conversation runs on its own, with its own event log and turns. It fits work that needs a split inside the current message. The capability comes from the built-in Multi-agent plugin. & in the composer is a structured mention. The parent actually creates a child by calling the delegation tool. See Delegation.

Graph Workflow

A Graph Workflow describes step dependencies first, then executes. The source file can enter Git. A published definition version is immutable. It fits a fixed flow that must be reused and versioned. The capability comes from the built-in Workflow Creator plugin. See Graph Workflow.

Automation

An Automation, on manual run or when the schedule fires, starts one ordinary turn, or one published Workflow version. It binds an exact version and an isolation policy. Split logic belongs to delegation or the graph. Automation decides when to start. See Automation.

A one-off review chain uses delegation, for example handing finished code to another agent for review. A flow that repeats weekly is written as a Graph, published, then started on a schedule by Automation.

Choosing

When this message needs another agent to take over, use delegation. When step order is stable, belongs in Git, and must be started repeatedly by Automation, use a Graph. When the only decision is when to start an already chosen target, use Automation.

Delegation is the mechanism by which a parent conversation hands a bounded subtask to another enabled agent. The child is an independent Conversation: its own event log, turns, and permissions. The parent keeps the relation, policy, and a result summary. The parent keeps a summary.

Mention and tool

& in the Composer is a structured mention, for example &Codex. It asks the parent to consider handing work to that agent. After & appears, the parent still creates a child only by calling delegate_to_agent. If the parent never delegates, no started child is shown. If the current parent lacks companion capability, the mention stays a reference.

Child rules

A child task completes once by default: the first turn reaching a terminal state ends it. Parallel delegations should bind different workspaces so each tree stays isolated. After the parent panel closes, child turns already running continue. Cancel happens on the child conversation or the delegation card. Child permission requests still need a person, with the same rules as any conversation.

Max delegation depth, completed-result cache, and sub-agent defaults live in the plugin config.json and apply only to new children started by delegation. Depth is 1–8, default 1.

Plugin boundary

The capability comes from the built-in Multi-agent plugin. It starts disabled and stays in the catalog. Plugin enablement is delegation enablement. While the plugin is off, & is an ordinary character. Mentions appear in conversations created or rebound after enable. How-to: Agent delegation.

Result return

The parent receives a summary and the return payload that was allowed. Completed results cache in memory for the running delegation session and clear when that session ends. A configured MB cap of 0 means no capacity cap. Release still happens when the session ends.

A Graph Workflow describes step order as a dependency graph. Source artifact, published definition, and run instance have separate identities.

Source and publish

The source file (*.vibex-workflow.json) can be edited repeatedly in a workspace and committed to Git. At that point it is the authoring fact. Publish, after validation, produces an immutable definition version. A failed validation produces no new version. A run binds the definition version at start. Later source edits affect the next version only. An Automation that targets a workflow binds that exact version.

Opening the source enters Workflow Studio. A debug run can execute only the selected step, or continue downstream from it. Debug uses an isolated test worktree. A debug breakpoint belongs to that Debug run only.

Steps

An Agent step runs through a child conversation and real turns. Continuing the dialogue creates a new turn. A cancelled turn stays cancelled. An Approval step waits for an authorized principal. Retry creates a new attempt and keeps the old record.

A completion gate decides how a candidate output is accepted. On manual confirm, Studio derives a visible confirm node that opens the agent-step conversation. When continuing may repeat side effects and the system has no contrary proof, the run enters needs review. A person chooses continue or stop.

Run control

A run binds one definition version, a set of inputs, and a workspace. A new run can be derived from a chosen step of an existing run. The original run stays read-only. Upstream results that still match the contract can be reused.

Pause first stops scheduling new steps, then cancels in-flight turns, and enters a resumable paused state. File and external side effects that already happened stay. Continue opens a new turn in the original child conversation. Merge, push, and publish finish in the Git panel.

Controller and worker

A user may authorize a Controller Agent, separate from the worker that executes a step, to inspect node evidence, append input, or accept a candidate output through Workflow MCP. Every control action is auditable. Workflow MCP depends on a running Host. When the Host is unavailable, publish, debug, and run entries close.

An Automation is a versioned trigger config. On manual start or when the schedule fires, it starts one ordinary turn, or one published Workflow version. Target kind is chosen at create. Turn and workflow stay that kind for the lifetime of the row.

Target and isolation

A single-session target creates a real Turn each run. A workflow target binds a published exact version. After the source publishes again, older automations keep the version they already reference.

The default is an independent worktree per run. Sharing the project root is an explicit choice and must pass a clean tree and branch check. Merge, push, or publish during a run still happen in the Git panel.

Spec JSON can be copied. Import resolves project, agent, and workflow references on the current Host and leaves the row disabled until enable is confirmed. The spec omits database identity, secrets, and machine paths.

Engine owner

One data directory has one automation engine owner: the current Host. Only the owner claims due jobs. If the page says another host holds the engine, the view is read-only.

On Host startup, leftover direct-turn runs become Interrupted. Runs already attached to a Workflow run follow that run’s terminal state. The next fire is still schedule or manual. After downtime, at most the most recent missed schedule is backfilled. Finished runs and their independent worktrees are kept 30 days by default, under a per-directory space quota. Running jobs are kept.

Run records

Each fire produces an Automation run. Terminal state follows the durable fact of the matching Turn or Workflow run. The list can run now, open history, and cancel a running row. Unseen failures surface on the row.

A VibeX plugin package is installed, enabled, updated, and uninstalled under one identity. One package may contribute UI, agent, Host, and runtime at once. Install treats it as a product package. There is no prior split into “platform plugin” versus “agent plugin”.

Lifecycle

Discover or import yields a source package. That is not yet execution rights. Install accepts an exact version/digest as the Host’s immutable install. New installs start disabled. Enable is the durable intent to publish contributions. After enable, the Host produces an activation generation: an atomic snapshot of package, grants, Runtime locks, and ready contributions. A candidate generation is invisible until fully validated. A failed update keeps the previous complete generation.

Conversations that already exist keep the tool list from creation. Later new or rebound conversations receive new contributions.

Turning enable off stops new turns from using the package’s contributions. History in the event log stays. A third-party package can be uninstalled: membership, agent bindings, and Skill projections go away. Conversation and automation history remain. Built-in packages stay in the catalog. The switch only enables them.

Trust

Enabling a VibeX plugin package allows it to run workers and UI with the same local rights as the Host. Separate processes exist for lifecycle, hot reload, and crash isolation. Package layout, content index, and validation are in the developer docs.

Agent-native plugins (Codex / Claude Code package formats) are held by that agent’s storage and trust. VibeX may project a read-only view and forward install/enable when the adapter is reliable. Native trust and VibeX enablement are separate authorities.

How-to: Install and enable a Plugin.

Control plane

The plugin control plane is the sole fact source for install, grant, start/stop, update, diagnostics, rollback, and uninstall. It can also read projections of agent-native plugins. Additions and deletions in native directories still follow that agent. External disable or a broken link must be shown as-is.

Identity

Plugin identity is stable Publisher plus Plugin ID. Display name, folder name, and similar contents leave identity unchanged. Packages with the same ID and different publishers keep separate grants and data. A linked development plugin keeps following a user-chosen directory. After the source changes, contributions, grants, and identity must be revalidated. The development directory stays on disk.

Plugin contributions attach by type to different places in the product. Usability is judged per contribution. A Skill inside the package is one contribution among others. Each contribution has its own identity, type, compatibility conditions, and readiness.

Contribution	Attach point
Skill / MCP	Agent conversation; visible to that agent after Agent binding
App UI	Preview, settings page, commands, custom surface in a VibeX window
Workflow	Orchestration; publish path matches the source file in the repo
Host Worker	Host background; clients observe a projection
Runtime	Exact CLI / Binary / sidecar version, resolved and locked by the Host

Binding and readiness

Enable allows those contributions to be published. Missing runtime, missing binding, or an agent that rejects the contribution leaves it unready. All-agents binding intent projects compatible contributions onto current and future enabled agents that support the capability. Exclusions are stored separately.

A Skill projection is a controlled read-only entry written to the agent-native Skill location. A user Skill of the same name stays. A Plugin Command and an agent-native command may share a display name and remain distinct by source identity.

A remote workstation changes state on the Host. Companion and chat-channel plugin management lives in Settings → Plugins on the Host or a workstation desktop.

Runtime lock

A Runtime requirement is an author declaration. The install lock records the exact version the Host resolved, integrity, and probe evidence. A successful declaration and a spawned process still require a passing probe before ready. A Host-owned Runtime enters reclamation only after references drop to zero.

The Host family ships official product plugins marked VibeX built-in. They start disabled and stay in the catalog. After the runtime is on disk, enable still has to be turned on. Later new or rebound conversations receive injection. The switch lives on the plugin itself.

Plugin	Effect after enable
Session Enhance	Questions, live feedback, session lookup, and session control
Multi-agent	& as a delegation mention; depth and child defaults apply to delegated children
Workflow Creator	Source edit, validate, debug, and publish
VibeX Office	Skills, workflows, and read-only preview for DOCX / XLSX / PPTX
Plugin Development	Local SDK / CLI and optional development MCP; everyday use can leave it off

Delivery

Official MCP ships with the Host family. After the plugin is enabled, the Host injects the matching MCP into later new or rebound agent sessions and trims tools/list per session. Conversations already open keep the tool list from creation.

The four Session Enhance tools can be turned off individually in plugin config. Multi-agent enablement is delegation enablement. Workflow Creator depends on the running Host loopback gateway. Office preview uses the Host-locked officecli Runtime.

Config writes each package’s config.json and applies to later new sessions or new previews.

Relation to Settings

Session tools and the delegation master switch live on those plugins’ Config tabs. Settings → General leaves those switches on the plugin pages. Office preview idle timeout and Workflow Creator’s default completion policy also live in each package config.