The upstream repo keeps one canonical term per concept in docs/glossary.md. This appendix condenses and adapts that vocabulary for this site, adds cross-links to the pages where each term is used, and defines a handful of additional terms this site relies on. The canonical source of truth remains docs/glossary.md.

Capability seams

capability-seam

A seam is a swappable capability with three roles: a Service Definition (the Cordis Service owning ctx.<key> and its vocabulary types — an abstract class such as ShellExecutor, never a TypeScript interface), one or more Service Providers, and one or more Consumers that inject the service. packages/shell is the canonical example: dsh-shell (definition), dsh-bash-local / dsh-bash-sandbox (providers), and dsh-tool-bash (consumer). Roles usually occupy separate packages but a package may own several when they are one concern. Source: docs/glossary.md, docs/architecture.md; see capability seams.

seam roles

The three named roles of a capability seam — Service Definition, Service Provider, Consumer. One role alone is not a seam; adding a capability means designing all three. Source: derived from docs/architecture.md; see capability seams.

capability-seams.md

The generated doc (docs/capability-seams.md) that lists every seam and core service in a single graph page. Used as the reference index for the three-role pattern. Source: docs/capability-seams.md.

Agent scope

agent-scope

scope — the unit of per-agent registration: a contribution (tool, prompt section, variable, restriction, listener) is either global (visible to every agent) or scoped (owned by exactly one scope key). The levels are flat: scoped registrations do not inherit down to subagents; subtree behavior is expressed with lineage data, never scope structure. Source: docs/glossary.md; see scope.

scope key

The opaque identity a scope is keyed by, compared by object identity. Harness convention: a live agent is the key of its own scope. Source: docs/glossary.md.

agent context

agent.ctx — the agent's scoped context. Registrations through it are scope-visible and scope-lifetime (one fact drives both), and listeners on it participate in that agent's scope-filtered dispatches. Source: docs/glossary.md.

scope carrier

The thisArg a scope-filtered dispatch carries (built by scopeTarget); its filter admits untagged listeners plus the subject's own. A subject-less carrier (no key) admits untagged listeners only. Source: docs/glossary.md; see scope.

scoped dispatch

The rule that an event about one agent's activity dispatches with that agent's carrier. Events about a registry itself (e.g. a tool was added) are registry-subject and stay unfiltered. Source: docs/glossary.md; see scope.

shadowing

Most-specific-wins name resolution: a scoped tool/section/variable replaces its same-named global twin for that scope alone. It is the per-agent persona and per-agent tool-variant mechanism. Source: docs/glossary.md; see scope.

restriction

A scope-local restriction (tools.restrict) that filters the global tool set for one scope (compose by intersection); scope-local registrations are merged after that filter. A filtered-away global tool is absent from the prompt and refuses execution, indistinguishably from a nonexistent one. Source: docs/glossary.md.

setup window

The creation slot where a creator composes an agent's scoped world (CreateAgentOptions.setup) — after the scope and agent object exist but before the agent or session is published, agent/session-start fires, or the first prompt is assembled. Setup registers; it never drives the agent. Source: docs/glossary.md.

lineage

Parent/child facts carried as data — parentSession, durable delegationDepth, runtime subagentDepth. Lineage never affects visibility. Source: docs/glossary.md; see subagent.

Goals

goal

One durable completion objective attached to an existing session, with a revisioned active / paused / blocked / complete phase and a goal-round cap; blocked retains a policy code and explanation. A goal is state — not a scheduler or a separate conversation; the session log remains its source of truth. Source: docs/glossary.md; see goals.

goal round

One continuation cycle admitted for the current goal. The same-session driver materializes a goal round as one goal-sourced turn, which can contain zero or more steps; unrelated human turns in the same session do not consume the goal-round cap. Source: docs/glossary.md; see goals.

goal activation

Process-local permission for a continuation consumer to admit another goal round. Activation is either armed or disarmed; it is deliberately absent from durable replay, so resume and fork require a later human-authorized resume mutation through /goal or the model tool before automatic work. Source: docs/glossary.md.

human command

A slash-prefixed instruction interpreted and executed by a human-facing adapter through ctx.commands, without becoming a model message. It is distinct from a model-facing tool and from shell command execution through ctx.shell. Source: docs/glossary.md; see commands.

command plane

Discovery, parsing, dispatch, cancellation, and result rendering owned by UI adapters and command plugins. Command output is UI state unless the handler separately mutates a durable domain. Source: docs/glossary.md; see commands.

goal command

The /goal human command contributed by dsh-command-goal; it observes or mutates the current goal directly while the goal domain owns every durable, model-visible record. Source: docs/glossary.md; see goals.

Loop hierarchy

turn

One drain of admitted input in a session, ending after the model and its tools stop or a terminal policy intervenes. Source: docs/glossary.md; see session agent loop.

step

One model request plus the tool executions caused by its response; a turn contains zero or more steps. Source: docs/glossary.md; see session agent loop.

round

An outer policy iteration containing a turn, such as a goal round or one fresh-agent Ralph attempt. Round counters belong to that policy and do not count every turn in a session. Source: docs/glossary.md; see goals, workflow.

Ralph

ralph loop

One foreground fresh-agent workflow run toward an immutable objective — a model-facing tool policy composed from workflow and subagent primitives, not a same-session goal, agent-loop mode, scheduler, or generic workflow-script feature. Source: docs/glossary.md; see workflow.

ralph round

One fresh child session in a Ralph loop. The child receives no parent or prior-child conversation seed; the shared workspace and one bounded Ralph handoff carry cross-round state. Source: docs/glossary.md.

ralph handoff

The normalized bounded structured report passed from one continuing Ralph round to the next — status, summary, evidence, next steps, blocker text. It supplements the shared workspace rather than replacing it as authority. Source: docs/glossary.md.

Composition and packaging (this site's additions)

These terms are used across this site but are not defined in the upstream glossary; definitions derive from docs/architecture.md and packages/boot/app-boot/README.md.

profile

A profile is a named composition stored in the Harness home ($DSH_HOME/profiles/<name>): it lists the bundles it stacks (dsh.profile.bundles), holds any out-of-tree plugins it installs, and keeps the user's own cordis.patch.yml. web and headless ship as templates. Source: docs/architecture.md, packages/boot/app-boot/README.md (Profiles); see bundles.

bundle

A bundle is a distribution format for Cordis config rows and the code they mount (dsh.bundle → cordis.patch.yml), so whatever it inserts stays patchable by the layers above it. dsh-base, dsh-web-app, and dsh-headless are the shipped bundles. Source: docs/architecture.md; see bundles.

patch

A patch targets a row by id and replaces its whole config, or inserts new rows (an id-targeted replace does not deep-merge — restate unchanged fields). Patch layers apply over an empty entry list in order: each bundle, then the profile's cordis.patch.yml, then the home-level one, then any --patch overlay. Source: docs/architecture.md, packages/boot/app-boot/README.md; see bundles.

harness home

The machine-local root that stores profiles, home-level patches, .env, and credentials; resolved through resolveDshHome ($DSH_HOME, else ~/.dsh). Source: packages/boot/app-boot/README.md, packages/util/home-paths/README.md.

developer preview

DeepSeek Harness's current status: the product is in developer preview and iterating rapidly, with compatibility-breaking changes expected. Treat the pinned revision as authoritative rather than any assumed API stability. Source: README.md (Developer preview).

Further reading

• Package index — where every seam, provider, and consumer lives.
• Map of official docs — the upstream docs/ tree the glossary derives from.
• docs/glossary.md — the canonical, full-length vocabulary (repo-relative).
• docs/architecture.md — profiles, bundles, patches, and seams explained (repo-relative).
• packages/boot/app-boot/README.md — the boot and profile machinery behind these terms (repo-relative).