/vflow

name: vflow
description: >-
  Query VelaTerm plan-execute workflows by session: find planner, executor and optional reviewer IDs, tasks, states,
  rounds, delivery receipts and saved session properties. Use when a workflow ID is unknown or the
  user asks which execute sessions belong to a plan session. Lookup is read-only; it does not dispatch,
  message, stop or accept work.

vflow

Use saved backend associations rather than guessing from session names or reading SQLite directly.

vflow list
vflow list <plan-session>

The first form queries the calling session. The second accepts a full session ID, an ID prefix of at least eight characters, an exact name, or a unique name substring. Quote names containing spaces. An ambiguous reference returns candidates; choose an exact ID. Lookup can inspect another session, including an archived session, in the same connected VelaTerm instance.

Read the JSON result:

• `session`, `parent`, `ancestors`, `children`: the resolved session, its parent, ancestor chain and

actual direct children, with saved properties and per-session settings.

• `workflows`: associated overall workflows, including saved configuration, state, round, latest

handoff summary, review configuration/status, planner, executor, optional reviewer, recent delivery receipts, and split `tasks`.

• `workflows[].tasks`: each task's name, prompt, independent workflow ID, state, round, and executor.
• `workflowIds` on a session: its direct workflow memberships; `parentSessionId` records its tree parent.

An empty `workflows` array does not mean there are no children. Inspect `children` separately and do not call every child a workflow executor. An executor may be absent before its first dispatch. Activity and delivery receipts do not prove task completion; check the saved state and execution evidence.

Session objects include project/group placement, agent and native conversation IDs, engine, directory, worktree and baseline ref, permissions, collaboration mode, preset, executable, shell, shortcut, mark, sort order, creation/archive timestamps, collapse/fork state, and saved model/effort, Codex, Claude and auto-continue settings. `launchModelSettings` separately reports model/effort explicitly saved in launch arguments. Null means the value was not saved; do not invent an effective default. `redactedFields` identifies masked launch input, environment values and URL credentials/query/fragment. Environment variable names remain visible. These masked values are not evidence that a setting is empty.

Workflow members can read a saved complete execution report with `vflow read-report <workflow-id> --message-id msg-UUID`. This does not dispatch or review work. For tool history, use `vrefer <executor-session-id>`; summaries can be truncated. For ordinary session hierarchy or properties without workflow details, use `vself [session] --json`.

Inside a workflow member session, `vflow status <workflow-id>` reads that workflow's detailed status. Unlike `list`, `status` requires the caller to be its owner, planner, executor or reviewer. Existing dispatch, stop, block, accept and finish commands retain their role and round checks. Read-only lookup does not authorize those actions. For an already authorized planning/execution handoff, read `../vspawn/references/plan-execute.md` and follow that protocol.

The commands require a VelaTerm-hosted session and its injected `VLX_*` environment. If `vflow list` reports an unknown action, the running backend predates lookup support; report the version mismatch instead of treating it as an empty workflow or editing the database.