@afokapu/atdd-flow 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alec Fokapu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# ATDD Workflow
+
+`atdd-flow` is a filesystem-first control plane for coordinated coding agents. It keeps durable coordination in a separate Git-backed **Desk**, not inside the code repositories and worktrees being changed.
+
+## The model
+
+```text
+Desk (private Git repository)             Code repositories / worktrees
+├── work/<project>/                       └── implementation only
+│   ├── project.yaml  policy
+│   ├── seats/        replaceable responsibilities and handoffs
+│   └── tasks/        delivery, criteria, and proof
+└── threads/          conversation and immutable messages
+```
+
+- A **seat** owns responsibility, branch, worktree, checkpoint, and host addresses; a **task** owns its brief, ownership, dependencies, criteria, and proof.
+- A **thread** owns messages, receipts, results, and decisions; a **host** owns panes and notifications—never durable state.
+
+A stable address, such as `driver.runtime@resolver-os`, survives a different pane, host, model, or replacement agent. A replacement reads its durable seat, task, checkpoint, and threads rather than predecessor-private context.
+
+Workflow is a YAML protocol and CLI—not a database, daemon, agent runtime, or task-management SaaS. Git supplies history and replication; a multiplexer may wake an agent, but never owns state.
+
+## Install and create a Desk
+
+Install locally in every code repository whose agents use Workflow:
+
+```sh
+bun add -d @afokapu/atdd-flow@latest
+```
+
+### Migrating from ATDD Workflow
+
+Install `@afokapu/atdd-flow` and replace `atdd-workflow` (including `bunx atdd-workflow`) with
+`atdd-flow`. Existing Desk YAML schemas and `ATDD_WORKFLOW_ROOT` remain compatible.
+
+The operator creates one private Desk for projects that coordinate together:
+
+```sh
+atdd-flow init "$HOME/Github/desk" --git
+export ATDD_WORKFLOW_ROOT="$HOME/Github/desk"
+```
+
+Use `--root "$HOME/Github/desk"` for one-off commands. Keeping the Desk separate avoids code-branch conflicts and permits cross-repository work.
+
+### Declare launch executables once
+
+`desk.yaml` owns the executable names that every seat may use. Give each name
+an absolute command path when the host does not guarantee a shared `PATH`:
+
+```yaml
+schema: atdd-workflow/desk/v1
+desk: desk
+application: tuios
+executables:
+  claude: /Users/you/.local/bin/claude
+  codex: /opt/homebrew/bin/codex
+  pi: /opt/homebrew/bin/pi
+  kimi: /Users/you/.kimi-code/bin/kimi
+```
+
+The executable registry is transport configuration, not model allocation. New seats do not pin an
+agent. Instead, `models.yaml` declares the launchable model portfolio in descending capability order:
+
+```yaml
+schema: atdd-workflow/models/v1
+models:
+  - id: frontier
+    executable: claude
+    args: [--model, opus]
+  - id: standard
+    executable: claude
+    args: [--model, sonnet]
+  - id: codex
+    executable: codex
+  - id: glm
+    executable: glm
+    enabled: false
+```
+
+Order is policy: strongest first, weakest last. Entries whose executable is unavailable, or whose
+`enabled` flag is false, are excluded. For ordinary phase work, Jev sees the seat's active work and
+selects the weakest available model sufficient for that responsibility. If model selection is unavailable
+or low-confidence, Workflow conservatively launches the strongest available model. Final behavioral
+review has its own bounded routing step described below. Older Desks without `models.yaml` continue
+to honor a legacy seat `agent` through the executable registry.
+
+## Configure worktrees and seats
+
+Create a project, then set its policy in `work/<project>/project.yaml`:
+
+```sh
+atdd-flow project init resolver-os
+```
+
+```yaml
+repository: /Users/you/Github/resolver-os
+worktree_root: /Users/you/Github/worktrees/resolver-os
+roles:
+  coordinator: { address: coordinator@{project}, branch: main, worktree: '{repository}' }
+  driver: { address: driver.{name}@{project}, branch: delivery/{name}, base: main, worktree: '{worktree_root}/{name}' }
+```
+
+The operator or coordinator creates seats; drivers do not choose their policy:
+
+```sh
+atdd-flow spawn resolver-os coordinator main --worktree /Users/you/Github/resolver-os
+atdd-flow spawn resolver-os driver runtime
+```
+
+`spawn` creates missing driver worktrees through Git: this example creates `/Users/you/Github/worktrees/resolver-os/runtime` on `delivery/runtime`. ATDD Bun owns safe retirement, not creation. A seat can own several tasks.
+
+## Deliver work
+
+```text
+todo → in_progress → review → done
+```
+
+The coordinator assigns; the driver implements, proves each criterion, and submits for review; only the coordinator marks the task done.
+
+```sh
+atdd-flow task add resolver-os runtime-rollout --title 'Complete runtime rollout' \
+  --coordinator coordinator@resolver-os --assignee driver.runtime@resolver-os \
+  --done-when 'Checks pass'
+atdd-flow task start resolver-os runtime-rollout --by driver.runtime@resolver-os
+atdd-flow task prove resolver-os runtime-rollout --by driver.runtime@resolver-os --item 1 --proof 'CI run 42'
+atdd-flow task review resolver-os runtime-rollout --by driver.runtime@resolver-os
+atdd-flow behavioral-review launch resolver-os runtime-rollout --by coordinator@resolver-os \
+  --application tuios --placement resolver-os --gate 'CI run 42'
+# the reviewer persists APPROVE, RETURN, or ESCALATE through behavioral-review record
+atdd-flow task done resolver-os runtime-rollout --by coordinator@resolver-os
+```
+
+Proof is a compact PR, CI run, report, commit range, deployment, or thread reference. Dependencies gate prerequisites; independent tasks are parallel-ready. Use `task block` only for a real external blocker, then checkpoint exact state and next action. For deliveries explicitly governed by the `workflow` ATDD Bun profile, `review → done` additionally requires a durable final behavioral-review result with decision `APPROVE` for the current clean delivery commit. For an idle driver’s final task, `task done ... --retire-assignee` delegates clean-and-merged worktree retirement to ATDD Bun.
+
+## Communicate and hand over
+
+Threads are the durable inbox/outbox. Workflow persists a message before a best-effort host notification, so a closed pane, rate limit, or missed prompt cannot lose it.
+
+```sh
+atdd-flow thread start --with coordinator@resolver-os,driver.runtime@resolver-os \
+  --subject 'Runtime rollout' --task resolver-os/runtime-rollout
+atdd-flow post T-... --from coordinator@resolver-os --to driver.runtime@resolver-os \
+  --expects-result --body 'Implement the task and return proof references.'
+atdd-flow result T-... M-... --from driver.runtime@resolver-os --body 'CI run 42; PR #81.'
+```
+
+For a shared boundary: driver → coordinator → affected coordinator(s) → minimum agreement in a thread → driver. `--to all` broadcasts; requested results remain outstanding until every recipient replies. Checkpoints are short handoffs, not logs; update at responsibility transitions and before replacing an agent.
+
+## Inspect, host, and guide agents
+
+```sh
+atdd-flow status
+atdd-flow status seat driver.runtime@resolver-os
+atdd-flow open driver.runtime@resolver-os
+```
+
+TUIOS is the primary live host; tmux and Herdr have notification adapters. TUIOS launch targets the named session, never the focused session:
+
+```sh
+atdd-flow attach driver.runtime@resolver-os --application tuios
+atdd-flow launch driver.runtime@resolver-os --application tuios --placement resolver-os
+```
+
+Launch selects a model from `models.yaml`, starts that model's executable in the seat's declared worktree, passes `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, records the selected model on the live runtime binding, and asks the agent to read its seat. Other hosts remain correct without an adapter; their operator supplies that prompt.
+
+With ATDD Bun, enable the Workflow profile:
+
+```yaml
+profiles: [planner, coder, tester, traceability, security, workflow]
+```
+
+The lifecycle convention makes agents read CLI help and durable records, prefer the smallest sufficient change, avoid speculative scope, work until review-ready or explicitly blocked, prove criteria, and coordinate boundaries through coordinators. ATDD Bun remains repository and merge authority.
+
+### Final behavioral reconciliation
+
+Phase work does not add a writer/reviewer pair after every artifact. The next phase consumes and
+semantically challenges the previous phase while ATDD Bun provides deterministic enforcement. The
+explicit independent review is reserved for the terminal integration boundary:
+
+```text
+implementation → deterministic gates → task review → JEV routing
+               → behavioral reviewer → coordinator decision → done/merge
+```
+
+ATDD Bun owns the substantive method through
+`atdd-bun.review.behavioral-reconciliation`. Workflow first runs deterministic ATDD Bun gates; a red
+gate prevents reviewer launch. JEV then classifies only the required review surface
+(`LOCAL | ASSEMBLED | JOURNEY | SYSTEM`) plus bounded routing signals such as proof boundary,
+cross-path scope, consequence, and runtime observability. JEV does not decide correctness.
+
+Workflow selects the reviewer model from `models.yaml`, creates a task-scoped reviewer seat in the
+delivery worktree, injects the full installed ATDD Bun review convention into the reviewer prompt, and
+presents inputs in intent-first order. The reviewer records a structured result with
+`APPROVE | RETURN | ESCALATE`; it never mutates task state. Review attempts are retained in
+`work/<project>/tasks/<task>.reviews.yaml` and are bound to a clean delivery commit.
+
+`APPROVE` makes the task eligible for coordinator completion. `RETURN` is evidence for the
+coordinator to move `review → in_progress`. `ESCALATE` leaves the task in review (or the coordinator
+may explicitly block it) while authoritative intent is resolved. Only the coordinator can transition
+`review → done`.
+
+## Optional Jev helper
+
+Jev is read-only; it cannot mutate state, approve proof, or override ATDD Bun.
+
+```sh
+atdd-flow scout --goal 'Fix payment retry behavior' --path src/payment/retry.ts --path src/profile/avatar.ts
+atdd-flow focus-check resolver-os runtime-rollout --action 'Add a generic retry orchestration service'
+```
+
+`scout` selects likely files. `focus-check` returns `REQUIRED`, `USEFUL_BUT_NOT_REQUIRED`, or `SPECULATIVE`.
+The final behavioral-review launcher also uses JEV System-1 for bounded routing questions only; low
+routing confidence becomes conservative `SYSTEM` routing. Use Jev judgments as routing advice, never
+as correctness or completion authority. If scouting or focus judgment is unavailable, use repository
+evidence and prefer the smaller reversible solution; if model selection is unavailable, escalate
+conservatively to the strongest available candidate.
+
+On macOS, Jev reads its TypeSafe key only from Keychain item `atdd-workflow.typesafe`; `TYPESAFE_API_KEY` is a temporary or CI override. The secret is never written to Desk records, output, Git, npm, or GitHub.
+
+## Command reference
+
+```sh
+bunx atdd-flow --help
+```
+
+Installed help is the authoritative syntax for that version.

package/bin/atdd-flow

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+
+import "../src/cli.ts";

package/conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml

@@ -0,0 +1,183 @@
+schema_version: 1.1.0
+rule_id: atdd-workflow.workflow.lifecycle
+kind: policy
+status: active
+name: Coordinate durable agent work through seats, tasks, and threads
+statement: >-
+  When the workflow profile is active, agents coordinate durable work through the locally installed
+  atdd-flow CLI and its YAML coordination root. A seat owns its runtime binding, branch and
+  worktree; a task owns its delivery state and proof; a thread owns its conversation. Drivers favor
+  the smallest effective implementation, coordinate shared-boundary decisions through their
+  coordinators, and continue assigned work until it is review-ready or explicitly blocked.
+terms:
+- term_id: workflow_root
+  text: >-
+    The separate coordination repository holding work/, threads/, and the durable YAML records.
+- term_id: seat
+  text: >-
+    A replaceable agent responsibility with a purpose, worktree/branch binding, checkpoint, and
+    optional native application addresses.
+- term_id: retirement
+  text: >-
+    The final housekeeping step for an idle driver seat. It is delegated to ATDD Bun rather than
+    performed with raw Git commands.
+- term_id: smallest_sufficient_change
+  text: >-
+    The least broad implementation that correctly satisfies the current task's done_when criteria
+    and the repository's existing conventions.
+- term_id: responsibility_boundary
+  text: >-
+    A point where implementation requires agreement about vocabulary, interfaces, contracts,
+    ownership, or responsibility shared with another seat or project.
+- term_id: boundary_handshake
+  text: >-
+    The coordinator-mediated agreement used when a driver reaches a shared responsibility boundary.
+    Coordinators resolve only the minimum shared contract necessary to continue implementation and
+    record that agreement durably in a Workflow thread.
+- term_id: review_ready
+  text: >-
+    A task state reached only after required implementation and verification are complete, every
+    done_when criterion carries proof, the task has been moved to review, and the coordinator has
+    received the result.
+- term_id: model_portfolio
+  text: >-
+    The models.yaml list of launchable model candidates, ordered strongest to weakest. Seats do not
+    normally own a model; Jev selects the weakest available candidate sufficient for the current work.
+- term_id: behavioral_review
+  text: >-
+    The independent final semantic reconciliation performed after deterministic gates and before a
+    Workflow-governed task may move from review to done. ATDD Bun owns the substantive review method;
+    Workflow owns routing, reviewer allocation, durable evidence, and lifecycle enforcement.
+content:
+  summary: >-
+    Use coordination records as the durable source of truth. Drivers implement the smallest effective
+    solution, coordinators resolve shared-boundary ambiguity, and an assigned task continues until
+    review-ready or explicitly blocked.
+  normative_text: |
+    Before taking workflow action in a repository, run `atdd-flow --help` to discover the
+    commands and current syntax available in the installed CLI. If the executable is project-local
+    and not on PATH, run `bunx atdd-flow --help`. Treat that help output as the command authority:
+    do not invent flags, infer command forms from memory, or rely on an older agent's instructions.
+
+    Start from the current seat, checkpoint, assigned tasks, and relevant thread records. A replacement
+    agent resumes from those records; it does not depend on a conversation with its predecessor.
+
+    A driver starts only its assigned ready task. Treat the task's done_when criteria as the required
+    delivery scope. Prefer existing repository patterns, components, dependencies, contracts, and
+    abstractions. When multiple implementations are correct, choose the smallest effective change that
+    agrees with the existing system.
+
+    Do not redesign adjacent systems, introduce generalized infrastructure, add dependencies, create
+    abstractions for hypothetical future requirements, or perform unrelated cleanup merely because the
+    opportunity was discovered. Broaden the implementation only when a done_when criterion requires it,
+    the current design cannot correctly satisfy the task without it, or the broader change is necessary
+    to resolve a verified blocker.
+
+    Work criterion by criterion. Continue from the next unmet done_when criterion through
+    implementation, verification, and proof rather than treating successful code generation as task
+    completion.
+
+    An autonomous work turn on an assigned in_progress task must not intentionally end while required
+    work remains actionable. Complete the required implementation, run the relevant tests and ATDD Bun
+    checks, correct failures caused by the work, record proof for every done_when criterion, move the
+    task to review, and send the coordinator a result. Continue until the task is review-ready or
+    explicitly blocked.
+
+    If completion is impossible, record the blocker, checkpoint the exact current state and next action,
+    and notify the coordinator. Do not silently leave actionable required work unfinished.
+
+    When a driver reaches a responsibility boundary involving shared vocabulary, endpoint shape,
+    contracts, artifact ownership, or another participant's responsibility, do not independently
+    redefine the shared contract. Send the concrete boundary question to the driver's coordinator.
+
+    The coordinator aligns directly with affected coordinators through the existing durable thread
+    mechanism. Resolve only the minimum shared vocabulary, interface, ownership, or responsibility split
+    needed for the current work. Prefer an existing convention or contract over inventing a new one.
+    Record the agreement in the relevant thread and communicate the result back to affected drivers.
+
+    Boundary coordination is not an invitation to redesign adjacent systems or solve hypothetical future
+    needs. A settled boundary decision remains in force unless implementation produces concrete evidence
+    that it cannot satisfy the task.
+
+    A driver waiting on a boundary decision continues any independent required work that remains
+    actionable. Mark the task blocked only when the unresolved decision prevents further meaningful
+    progress.
+
+    Use `atdd-flow scout` only when repository scope is genuinely unclear or candidate files are
+    numerous. Use `atdd-flow focus-check` only before a likely scope expansion such as a new
+    dependency, generalized abstraction, persistent schema, architecture change, adjacent refactor, or
+    unrelated defect. These read-only Jev judgments advise scope; they do not own correctness or completion.
+
+    New seats do not pin a model. The Desk's models.yaml is ordered strongest to weakest, and ordinary
+    launches ask Jev for the weakest available model sufficient for the seat's current active work. If
+    Jev model selection is unavailable or low-confidence, use the strongest available configured model.
+    A legacy Desk without models.yaml may continue to use its pinned seat agent.
+
+    Do not add a writer/reviewer pair after every development phase. The next phase consumes and
+    semantically challenges the prior phase while active ATDD Bun conventions provide deterministic
+    enforcement. Reserve the explicit independent semantic reviewer for the final integration boundary.
+
+    A driver records proof for every done_when criterion, moves the completed task to review, and sends
+    its coordinator a result. Before a final behavioral reviewer is launched, Workflow runs the
+    deterministic ATDD Bun gates in the delivery worktree. If a strict gate is red, do not invoke the
+    semantic reviewer; return the discrepancy to the appropriate implementation phase.
+
+    After deterministic gates pass, Jev may answer only bounded routing questions for final review. It
+    classifies the required review surface as LOCAL, ASSEMBLED, JOURNEY, or SYSTEM and supplies routing
+    signals such as behavior-affecting versus behavior-preserving intent, highest relevant proof
+    boundary, cross-path scope, consequence, reconciliation shape, runtime observability, and confidence.
+    Jev must not approve a delivery, decide semantic correctness, mutate task state, or redefine intent.
+    Low-confidence routing is treated conservatively as SYSTEM.
+
+    Workflow maps the bounded routing result through models.yaml to select a reviewer model, creates a
+    task-scoped reviewer responsibility in the delivery worktree, and provides the reviewer inputs in
+    this order: task criteria/source; relevant plan artifacts; deterministic gate evidence; executable
+    proof; runtime/worktree; then implementation/diff context. The complete installed
+    atdd-bun.review.behavioral-reconciliation convention is the authoritative review method and must be
+    included in the reviewer prompt. Workflow must not duplicate that methodology in its own convention.
+
+    The reviewer records durable structured evidence containing intent sources, expected behavior,
+    exercised boundary and evidence, observed behavior, reconciliation findings, a decision of APPROVE,
+    RETURN, or ESCALATE, rationale, and confidence. The reviewer does not mutate task state. APPROVE
+    makes the current clean delivery commit eligible for coordinator completion. RETURN is evidence for
+    the coordinator to move review back to in_progress. ESCALATE leaves the task in review, or the
+    coordinator may explicitly block it, until authoritative intent is resolved. Only the coordinator
+    may move review to done.
+
+    For repositories explicitly governed by the workflow profile, Workflow deterministically prevents
+    review -> done unless the latest behavioral-review attempt is complete, records APPROVE, and matches
+    the current clean delivery commit. These checks prove that the required review occurred and applies
+    to the delivery being completed; they do not prove the reviewer's semantic judgment is correct.
+
+    A driver seat may own more than one task. A coordinator uses
+    `atdd-flow task done <project> <task> --by <coordinator> --retire-assignee` only when every
+    task assigned to that driver in the project is done and the seat is intentionally being retired.
+    That operation delegates to `atdd-bun worktree finish --delete-branch`; do not remove a worktree,
+    delete a delivery branch, or force cleanup through raw Git. A failed retirement leaves the task in
+    review and writes a blocked checkpoint for investigation.
+
+    Before working in or retiring a driver worktree, install that repository's local dependencies there.
+    Retirement resolves ATDD Bun from the worktree's local node_modules/.bin so it does not depend on a
+    developer's global executable installation.
+
+    Use the atdd-flow CLI to mutate workflow records. Read task, seat, checkpoint, and thread YAML
+    before acting; do not treat terminal pane history, a multiplexer, an optional judgment helper, or an
+    agent's private memory as durable coordination state.
+  fix_hint: >-
+    Return to the assigned task and its unmet done_when criteria. Remove speculative scope that is not
+    required for correctness. Resolve shared boundary ambiguity through the relevant coordinators.
+    Complete remaining verification and proof, or explicitly record the blocker and next action.
+  exceptions:
+  - A broader change is permitted when it is necessary to satisfy the current task correctly or resolve
+    a verified blocker.
+  - A driver may continue independent work while waiting for a boundary decision.
+  - A task may be completed normally without retiring its assignee when that driver still has work.
+  - A live host may notify an agent to inspect its seat, but it never owns the durable state.
+  - An optional Jev scouting, focus, final-review-routing, or model-selection judgment may advise
+    execution, but it never owns task state, proof, correctness, or completion authority.
+metadata:
+  aliases:
+  - ATDD-WORKFLOW-LIFECYCLE
+  introduced_in: 0.1.3
+implementation:
+  type: none

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@afokapu/atdd-flow",
+  "version": "0.2.0",
+  "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
+  "type": "module",
+  "bin": {
+    "atdd-flow": "bin/atdd-flow"
+  },
+  "scripts": {
+    "workflow": "bun run src/cli.ts",
+    "check": "bun run src/cli.ts --help",
+    "test": "bun test"
+  },
+  "files": [
+    "bin",
+    "conventions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "atdd",
+    "workflow",
+    "agents",
+    "multi-agent",
+    "coordination",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/afokapu/atdd-flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/afokapu/atdd-flow/issues"
+  },
+  "homepage": "https://github.com/afokapu/atdd-flow#readme",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "devDependencies": {
+    "@afokapu/atdd-bun": "^0.10.44"
+  },
+  "dependencies": {
+    "@typesafe-ai/sdk": "^0.6.0"
+  }
+}

package/src/adapters.ts

@@ -0,0 +1,88 @@
+import { run } from "./core";
+
+type Environment = Record<string, string | undefined>;
+
+const value = (environment: Environment, name: string, application: string) => {
+  const current = environment[name];
+  if (!current) throw new Error(`Cannot discover ${application} here: ${name} is not set.`);
+  return current;
+};
+
+/**
+ * Native host location discovery. These values come from the host process,
+ * rather than from an agent, title, label, or whichever pane happens to have
+ * focus in the UI.
+ */
+export function discoverAddress(application: string, environment: Environment = process.env): string {
+  const discoverers: Record<string, () => string> = {
+    herdr: () => value(environment, "HERDR_PANE_ID", "Herdr"),
+    tmux: () => value(environment, "TMUX_PANE", "tmux"),
+    tuios: () => `${value(environment, "TUIOS_SESSION", "TUIOS")}/${value(environment, "TUIOS_WINDOW_ID", "TUIOS")}`,
+  };
+  const discover = discoverers[application];
+  if (!discover) throw new Error(`No deterministic discovery adapter is installed for ${application}.`);
+  return discover();
+}
+
+export function notificationCommand(application: string, address: string, notice: string): string[] | undefined {
+  const commands: Record<string, () => string[] | undefined> = {
+    tmux: () => ["tmux", "send-keys", "-t", address, notice, "Enter"],
+    // A Herdr pane id is the canonical runtime address. `pane send-text` is
+    // supported by both standalone Herdr and TUIOS's embedded Herdr server;
+    // `agent send` is not available on every embedded-server version.
+    herdr: () => ["herdr", "pane", "send-text", address, notice],
+    tuios: () => {
+      const separator = address.indexOf("/");
+      if (separator < 1 || separator === address.length - 1) return undefined;
+      return ["tuios", "queue", "-s", address.slice(0, separator), "-w", address.slice(separator + 1), notice];
+    },
+  };
+  return commands[application]?.();
+}
+
+export type LaunchRequest = {
+  application: string;
+  placement: string;
+  name: string;
+  worktree: string;
+  agent: string;
+  args?: string[];
+  environment?: Record<string, string>;
+  root: string;
+  seat: string;
+};
+
+/** A launch placement names a host container, never the currently visible UI. */
+export function launchCommand(request: LaunchRequest): string[] {
+  const environment = [
+    "/usr/bin/env",
+    `ATDD_WORKFLOW_ROOT=${request.root}`,
+    `ATDD_WORKFLOW_SEAT=${request.seat}`,
+    ...Object.entries(request.environment ?? {}).map(([key, value]) => `${key}=${value}`),
+    request.agent,
+    ...(request.args ?? []),
+  ];
+  if (request.application === "tuios") {
+    return [
+      "tuios", "new-window", request.name,
+      "-s", request.placement,
+      "--cwd", request.worktree,
+      "--no-focus", "--print-id", "--",
+      ...environment,
+    ];
+  }
+  throw new Error(`No deterministic launch adapter is installed for ${request.application}.`);
+}
+
+export function launchedAddress(application: string, placement: string, output: string) {
+  if (application !== "tuios") throw new Error(`No deterministic launch adapter is installed for ${application}.`);
+  const window = output.split(/\s+/)[0];
+  if (!window) throw new Error("TUIOS created a window without returning its id.");
+  return `${placement}/${window}`;
+}
+
+export async function notify(application: string, address: string, notice: string) {
+  const command = notificationCommand(application, address, notice);
+  if (!command) return;
+  await run(command, true);
+}