AgentSquad Delivery Language

This page is the ubiquitous language for generic AgentSquad delivery. Use these names in Studio, Temporal, LangGraph, Armory, workspace shims, tests, and runbooks. Do not add product-specific names such as a customer, legacy source, or stack name to the generic AgentSquad lifecycle.

Execution Boundary

Temporal workflow owns durable workspace/source/process lifecycle deadlines.
LangGraph Agent Server owns graph state, mailbox/frontier routing, slot intent, checkpoints, and next action.
Harness Runtime executes agent attempts through provider adapters.
Studio owns operator control, read models, reports, and observability views.
Armory owns MCP, skill, secret, browser-slot, and CLI loadout composition.
AgentSquad is the generic project-delivery graph template.
delivery graph kind names the product workflow shape, such as project_delivery, project_orchestrator, or fractalops_platform.
agent process adapter names how one agent attempt is executed, such as claude-cli, codex-cli, workspace-cli, or browser-only.
assembly worktree is the shared read/observation checkout for cross-repo context.
agent-owned worktree is the writable Git worktree for one agent lane.
execution surface is the AgentSquad-facing name for the provider surface where work can run. At platform/API boundaries this is still a runtime asset.
execution workspace is the per-run workspace where an agent process works.
workspace bootstrap asset is a file delivered into an execution workspace before the agent process starts.
source ref bundle is a workspace bootstrap asset used as read-only legacy or reference source material.

Agents may use terminals. Guardrails block unsafe ownership and invalid lifecycle claims, not shell access itself.

MCP Tool Naming And Loadout Federation

Armory composes MCP loadouts on top of the ContextForge gateway, which federates each yamon grid (searxnggrid, agent-memory-archive, datahub, glitchtip, playwright). Three names exist for the same tool; keep them distinct.

bare upstream name: the tool the grid actually exposes. Grids expose bare names, e.g. search_query on searxnggrid. The grid does not add a prefix.
federated wire name: the name the gateway serves. Each grid is registered as a federated gateway named yamon-<server_id>, and the gateway prefixes that grid’s tools with its slug, so search_query on searxnggrid is served as yamon-searxnggrid-search-query. A virtual MCP server named <server_id> (e.g. searxnggrid) bundles those prefixed tools at /servers/<hash>/mcp. The yamon-<grid>- prefix is added by the gateway, not the grid.
agent-facing name: the short bare name shown to the agent, mcp__<server_id>__<bare_tool> (e.g. mcp__searxnggrid__websearch_like). Agents never see the doubled federated form (mcp__searxnggrid__yamon-searxnggrid-websearch-like). Keeping the palette bare saves tokens and stays readable.

The workspace runtime adapter translates the agent-facing bare name into the gateway’s federated wire name only on the proxy call. The agent’s tool palette never carries the federation prefix.

Canonical Tool Matching

The grounding first-tool gate and tool-coverage matching compare tool names canonically: strip the yamon-<server>- federation prefix and normalize snake/kebab differences. A call is credited whether it is observed in bare form (the cliproxy runtime, where the workspace shim builds the palette) or in federated form (the claude-native runtime, which discovers names directly from the gateway). Neither runtime wrongly trips the grounding gate for the same tool.

Allow-List Shape

A loadout allow-lists one per-server wildcard mcp__<server_id>__*, not enumerated tool names. The wildcard matches both the bare names the cliproxy shim expands and the federated names claude-native discovers, and it survives upstream tool add/rename. Least-privilege is enforced at the server-attachment level — which MCP servers a loadout mounts — not per individual tool.

Runtimes

cliproxy runtime (squad default): endpoint binding central_cliproxy, model glm-5.2. The workspace shim builds the LLM tool palette from the bare upstream names and proxies MCP calls, translating to the federated wire name on the call.
claude-native runtime (fallback): connects to the ContextForge gateway directly and discovers the federated wire names from it.

Execution Naming Spine

Never use bare runtime when a narrower noun exists. In AgentSquad delivery, say runtime only when you mean one of these compatibility/platform nouns: Harness Runtime, runtime asset, or runtime image. Everywhere else, pick the noun by the question the code is answering:

Question	Use This Name	Example
Who owns lifecycle deadlines and activity retry?	`Temporal workflow`	workspace warmup activity retry
Who owns graph state and next action?	`LangGraph Agent Server`	mailbox/frontier thread
What provider surface can execute work?	`execution surface`	Daytona, Dokploy executor, PlaywrightGrid
Where is this attempt’s filesystem?	`execution workspace`	Daytona sandbox lease
Which process/tool mode runs the agent attempt?	`agent process adapter`	`claude-cli`, `codex-cli`, `browser-only`
What file is copied before launch?	`workspace bootstrap asset`	source tarball, proof bundle
What image is deployed?	`deploy image`	`fractalops-api` container image

Harness Runtime
  -> execution surface
     -> execution workspace
        -> agent process adapter

Temporal workflow: durable lifecycle owner. It decides phase deadlines, activity retry, timers, and long waits.
LangGraph Agent Server: graph owner. It decides mailbox/frontier routing, slot intent, checkpoints, and next action.
Harness Runtime: execution adapter boundary. It starts agent attempts through the selected provider surface.
execution surface: managed machine, cluster, service, or executor endpoint FractalOps can address. It maps to runtime asset at platform/API boundaries.
execution workspace: per-run/per-session workspace lease, usually a Daytona sandbox/workspace.
agent process adapter: one attempt executor, such as Claude CLI, Codex CLI, workspace CLI, browser-only, or LangGraph-native.
deploy image: deployable container artifact. It is not the lifecycle owner and not the workspace lease.

File movement is not runtime. Use workspace bootstrap asset for files delivered before launch and source ref bundle for legacy/reference source archives.

Execution Vocabulary Stack

Use the narrowest noun. Do not collapse these layers into runtime.

Layer	Canonical Name	Owns	Example Values
Workflow lifecycle	`Temporal workflow`	workspace/source/process deadlines, activity retry, timers	workspace provision activity
Agent graph	`LangGraph Agent Server`	graph state, mailbox/frontier routing, slot intent, checkpoints	delivery thread
Delivery shape	`delivery graph kind`	product workflow template	`project_delivery`, `project_orchestrator`
Agent executor	`agent process adapter`	one attempt’s process/tool mode	`claude-cli`, `codex-cli`, `browser-only`
Machine surface	`execution surface`	managed VM/LXC/Kubernetes/service endpoint	Daytona, PlaywrightGrid, Dokploy executor
Per-run lease	`execution workspace`	workspace assigned to a run/session	Daytona sandbox/workspace
Source transfer	`workspace bootstrap asset`	launch-time file delivery	tarball, CLI package, proof bundle
Deploy artifact	`deploy image`	container image built/released by CI	`fractalops-api`, agent server image
Git ownership	`agent-owned worktree`	writable delivery branch	backend/frontend/tester worktree
Shared context	`assembly worktree`	read-only cross-repo observation	assembly repo checkout
Operator projection	`Agent HUD`	compact human/control read model	status, wall, blocker, mailbox

Forbidden shortcuts:

Do not call an execution workspace a runtime.
Do not call a workspace bootstrap asset a runtime asset.
Do not call a runtime image Harness Runtime.
Do not call a deploy image an execution surface.
Do not call a delivery graph kind an agent runtime.
Do not call BOARD_STATUS a board concept in new code. It is a legacy wire alias for AGENT_HUD_STATUS.

Retire these overloaded phrases in new code and docs:

Old Phrase	Replacement
`agent runtime`	`agent process adapter` when it means CLI/browser mode
`workspace runtime`	`execution workspace`
`runtime source bundle`	`workspace bootstrap asset` or `source ref bundle`
`runtime deploy`	`deploy image release` or `GitOps rollout`
`runtime status`	`executionWorkspacePhase`, `agent attempt status`, or `Agent HUD status`
`runner`	`agent process adapter` for the executor, `Temporal worker` for activities
`runtime asset` in AgentSquad prose	`execution surface` unless the text names the platform API contract
`runtime image` in AgentSquad prose	`deploy image` unless the text names the compatibility field

Naming Guardrails

Do not use runtime as a generic synonym for every moving part. It only names the execution engine or managed execution surface. File delivery, source materialization, and worktree checkout each have their own names.

Use	Meaning	Do Not Call It
`Harness Runtime`	provider adapter boundary for agent attempts	lifecycle owner, Studio, worker
`delivery graph kind`	run/template workflow shape	agent runtime kind
`agent process adapter`	attempt execution adapter	delivery graph kind
`execution surface`	owned machine/service surface	workspace, source asset
`execution workspace`	Daytona/workspace lease for an agent	runtime, repo
`workspace bootstrap asset`	file copied/downloaded before launch	runtime asset
`source ref bundle`	read-only legacy/reference archive	source repo, runtime
`deploy image`	deployable container artifact	Harness Runtime, execution workspace
`agent-owned worktree`	writable Git lane checkout	workspace root
`assembly worktree`	shared read-only multi-repo context	owned repo

Legacy wire fields may still say runtime_kind or runtimeKind. Read them by scope:

Studio run/template/session metadata runtime_kind means delivery graph kind.
Harness payload/spec metadata runtimeKind means agent process adapter.
Environment and topology fields containing runtime usually mean runtime asset or provider configuration; do not infer Harness lifecycle from them.

New code should prefer explicit local variable names. Only emit the legacy field names at API, database, or payload boundaries.

Legacy BOARD_STATUS is a wire-compatible alias for AGENT_HUD_STATUS. New application code should read/write blocker_code, wall_code, executionWorkspacePhase, and AGENT_HUD_STATUS; only payload adapters should preserve BOARD_STATUS.

workspaceBootstrapAssets[] is the reusable file-delivery contract. Product source archives, CLI packages, proof bundles, or other launch-time files may use it. sourceRefBundleUrl is only a convenience alias that lowers into workspaceBootstrapAssets[].

Agent Identity And Handoff

Use these names when adding code, tests, docs, prompts, or telemetry:

role_id: stable capability lane such as frontend, tester, or committer.
agent_id: persisted routing identity for a Studio agent session. It may match a role in old records, but new language must not treat it as a human name.
agent_nickname: generated display identity for humans and mail. It is never used for routing, ownership, authorization, or Git branch ownership.
sender_agent_id: the agent that created a handoff message.
recipient_agent_id: the agent that must act on a handoff message.
dialogue_peer_agent_id: the other side of an open conversation from one session’s point of view.
delivery_reference: PR or issue URL plus branch/repository evidence.

Avoid new code or docs that use target without a noun. If a persisted API or database field still says target_agent_id, treat it as the wire-compatible alias for recipient_agent_id. If a persisted field says dialogue_target_agent_id, treat it as the wire-compatible alias for dialogue_peer_agent_id.

Handoff instructions must carry intent and success condition, not only the recipient:

sender_agent_id
recipient_agent_id
handoff_intent
required_result
delivery_reference
fallback_wall

Run Control Lifecycle

Use one lifecycle name for operator-driven agent replay:

Schedule Run Control -> Execute Pending Run Control -> Record Agent Attempt

Run Control is the durable operator command stored on the Studio run.
Scheduled Run Control means Studio has persisted pendingRunControl and emitted operator_control:scheduled.
Execute Pending Run Control means the background executor consumes that pending command and enters the Temporal-owned lifecycle.
Agent Attempt is the CLI/browser/runtime execution created by Harness Runtime under the current Temporal phase.

Avoid near-synonyms such as dispatch queued, session control queued, or retry background dispatch in new code and tests. Portal and Studio Admin must both persist the scheduled run control before starting background execution.

Delivery Proof

controller message: the operator or graph instruction carried into the next agent attempt.
delivery reference: a GitHub pull request or issue URL proving where agent work converges.
missing delivery reference blocker: runtime blocker github_issue_or_pr_link_missing.
project delivery evidence: durable proof attached to the issue, PR, report, DataHub lineage, or browser evidence surface.
handoff: a structured inbox transfer to another agent. A handoff is not a delivery reference.

Merge Lifecycle Decision

merge lifecycle decision is the committer’s closed decision after inspecting linked PRs and tester proof. The canonical runtime blocker is merge_lifecycle_decision_required.

A committer can close the decision in one of two ways:

handoff_state=merge_requested
merge_gate_status=qa_passed

or:

handoff_state=merged

committer_merge_state_required is a legacy alias only. New code, docs, tests, and prompts must use merge_lifecycle_decision_required.

Mechanical Walls

Mechanical Wall is a guardrail that detects agent behavior drifting away from AgentSquad intent and maps it to a specific fallback prompt or tool path. It is not a blocker.

Planner wall: if the lane declares the memory tool contract but the agent did not use it, retry with the memory-tool fallback prompt.
Tester wall: if evidence-capable tools such as PlaywrightGrid are available but no evidence attachment exists, retry with the evidence-capture fallback prompt.
Closer wall: if DataHub context or lineage evidence is required but missing, retry with the lineage-publication fallback prompt.
Committer wall: if a delivery reference exists but no merge lifecycle decision exists, retry with the merge-decision fallback prompt.
Delivery wall: if an agent leaves source/config changes in the owned worktree without a PR commit, retry the same worktree and require commit/push or a github_app_pr_handoff built from current file contents.

A blocker is a no-progress report from an agent or runtime. A wall may produce or clear a blocker, but the wall itself is the mechanical guidance system. Product-specific migration prompts may choose work, but they must not redefine the AgentSquad delivery vocabulary.