# Configuration
This document covers target-repo bootstrap, generated files, and the runtime
configuration that `opensymphony run` expects.
For a first multi-repository setup, read [multi-repository projects](multi-repository.md)
before the field reference below. For a local ACP agent, start with the
[ACP harness guide](acp.md). Repository routing and harness selection are
independent choices in the same selected config.
Operator projections expose project and repository identity through safe
aliases, canonical IDs, and safe remote fingerprints. Credential-bearing
remote URLs and raw credential values are excluded.
## Central configuration
`opensymphony run` selects configuration before it reads any repository
checkout. Selection order is:
1. `--config <path>`;
2. `~/.opensymphony/config.yaml`;
3. `./config.yaml` during the explicit legacy compatibility window.
Central files use `schema_version: 1` and own instance roots, routing mode,
tracker profiles, project sets, Linear projects, repository inventory,
credential references, review profiles, scheduler, integration, workspace, and
memory-catalog policy. Relative paths resolve from the central config file.
Remote values may contain no credentials, repository aliases are unique, and
strict unknown fields fail before tracker polling or workspace creation.
The central loader trims surrounding repository-alias whitespace before
building the routing inventory, so managed labels and legacy defaults resolve
against the same canonical alias key.
The active project's provider ID and optional provider slug are routing keys;
if any such key is shared by multiple active projects, their allowed
repository sets must be identical or central configuration fails as ambiguous.
The inventory generation hashes the normalized alias-to-identity map, so an
alias change advances the generation even when the underlying repository
identities are unchanged.
Canonical identities normalize the default authority for public providers, so
equivalent `owner/repository` and provider URL locators resolve to the same
durable repository identity and safe fingerprint. A Linear project association
constrains the allowed aliases but never supplies a terminal task's binding.
Any central-only key such as `instance`, `routing`, `tracker_profiles`, or
`repositories` selects the strict central parser, even when its discriminator
is malformed; those files fail closed instead of falling through to legacy
current-directory discovery. A legacy file containing only `schema_version`
remains on the legacy parser. `compatibility.allow_repo_local_config` is currently unsupported
and must remain `false`; setting it to `true` fails validation rather than
silently discarding repository-local orchestration settings.
Before tracker or workspace initialization, each run claims a process-lifetime
`.opensymphony-instance.lock` in every configured state and workspace root.
The lock prevents two instances from sharing runtime state; a live owner fails
startup, while a marker whose PID is no longer alive is atomically quarantined
and reclaimed. Legacy runs claim their configured workspace root as well.
The `openhands.front_matter` subsection carries the complete typed OpenHands
transport, local-server, conversation/LLM, subscription-reference, and
WebSocket profile when a workflow is migrated. `scheduler.retry.max_attempts`
is enforced as the maximum number of automatic retries; omitted values retain
the legacy retry behavior.
`workspace.retain_failed` applies only to failed or retry-exhausted outcomes.
The explicit `legacy_single` compatibility path retains terminal workspaces as
before, including successful, cancelled, and tracker-terminal releases. Future
strict routing may opt into terminal cleanup only through an explicit policy.
For strict repository-bound terminal tasks, each inventory entry also resolves
the target branch, credential environment-variable reference, instruction
path, and review profile into the checkout policy. Credential values are used
only while staging the clone; they are not written to remotes, manifests,
prompts, logs, or process arguments. The resulting config and inventory
generations are copied into the run envelope and must match on recovery.
The checkout credential must match the clone transport: `ssh-agent` is valid
for SSH clone URLs, while `environment` credentials are rejected for SSH
clones. Active GitHub review profiles must separately resolve to an
`environment` credential with a variable name, because review API requests do
not use the checkout transport credential or ambient authentication.
Parent repairs snapshot the selected repository's target branch, instruction
hash, review profile, review provider, review-policy generation, required-check
and required-review flags, and canonical lowercase merge method. Repository
instructions guide the repair but cannot weaken that central policy. GitHub PR
creation and merge use the review credential; branch fetch and push use the
checkout credential.
GitHub and Codex review profiles are supported for GitHub repair PRs; selecting
either GitHub-backed profile for a non-GitHub repository is rejected during
central configuration validation. A Codex profile
uses PR opening for its initial scan and the exact `@codex review` comment only
after a requested-change repair produces a new head. The completed review
summary closes the scan before current-head inline findings determine the
durable review result. The same current-head Codex and human evidence is used
when a completed child PR contributes merge evidence to a project-set parent.
Parent checkout maps written before these review fields existed are migrated
from the current central repository profile before reuse and written back to
both generation-bound copies.
Queued retries do not advance the durable retry count until dispatch begins, so
a restart during the backoff window cannot mistake a pending retry for an
exhausted one. Recovery restores persisted non-exhausted retry counts before
redispatch, while terminal tracker reconciliation removes stale exhaustion
markers. Once the limit is reached, the instance state root records a
retry-exhaustion marker before a disposable failed workspace is removed; the
marker keeps the issue parked across a later run.
Pending retry manifests also retain their scheduled time, due deadline,
reason, and redacted error summary, so recovery preserves the original
backoff instead of redispatching immediately.
While a retry is queued, the scheduler includes it in the frequent tracker
state refresh; a binding mutation is therefore reconciled before the retry's
due time rather than dispatching the old repository generation. Bounded detail
lookups also recheck configured project membership after hydration, protecting
against tasks moved out of the selected Linear project between full refreshes.
The instance-level retry marker remains until the replacement `start_run`
metadata is durable, even when replacement workspace materialization succeeds;
this closes the crash window between workspace preparation and run ownership.
If recovery finds both that metadata-only workspace and the instance retry
marker, it merges the marker into the workspace recovery instead of discarding
the retry budget. An external retry marker is restored only when the current
project-filtered active snapshot proves the issue is still dispatchable;
otherwise the stale marker is cleared. If the recovered issue manifest proves
a different canonical repository than the live binding, recovery removes the
old workspace before restoring the retry so normal dispatch rematerializes it
safely. Legacy-single routing also never applies its default repository to a
parent task. When a recovered run still points at the same canonical
repository, its persisted config and inventory generations remain attached to
that run; a formatting-only locator change cannot relabel an in-flight attempt
as a newer configuration generation. Scheme-default authority ports are
normalized for repository identity, while non-default ports remain distinct.
The same frequent refresh reads current child presence, so a running task that
becomes a parent is made repository-neutral and its old worker generation is
superseded before another turn can continue.
If a crash leaves a `Preparing` or `Prepared` run without a conversation
manifest, recovery consumes that attempt as a reconciliation retry and still
enforces `scheduler.retry.max_attempts`.
If OpenHands has accepted a prompt but the process exits before its run trigger
is acknowledged, the conversation manifest records a trigger-pending phase;
recovery reissues the idempotent trigger before observing the turn.
The supported routing variants are explicit:
```yaml
routing:
mode: legacy_single
repository: github:repository:example
```
`legacy_single` keeps unlabelled existing tasks on one configured repository.
That repository must also appear in the sole selected Linear project's
`repositories` association set; a mismatch fails before tracker polling so a
legacy run cannot execute a project's tasks from an unrelated checkout.
Central repository checkout policies are consumed only by `project_set`
routing; legacy runs continue to use their configured `checkout_path` and do
not require clone credentials or verified-generation acquisition.
The repository inventory entry's `instructions.path` is resolved beneath its
configured checkout and is the workflow file loaded for that legacy run;
repository implementation guidance remains separate from central front matter.
`project_set` enables multi-repository routing. Each active project's
repository association is resolved before tracker polling; tasks without a
canonical binding are blocked rather than falling back to the current
directory. Operational recovery commands (`debug` and `rehydrate`), plus all
doctor modes, use the selected repository policy and verified checkout
envelope, and refuse attach when binding or provenance is incompatible.
`rehydrate` also accepts `--config <path>` when an instance is not the default
home configuration. `memory init` refuses to treat a selected central config
as a repository-local memory file; initialize the local memory config instead.
When a project set supplies hash-pinned integration instructions, the resolved
artifact is carried into parent worker construction. Parent launch rereads the
artifact and verifies its configured hash before composing the prompt. The
artifact may describe topology-specific commands, but repository instructions
remain separate sections keyed by canonical repository ID and the runtime does
not convert those instructions into repository roles.
Every run records one `sha256:` config generation in startup diagnostics and
the initial control-plane event. Resolved credential values are never part of
the central model or its serialized diagnostics.
`linear_projects.<alias>.provider_project_id` is the provider project identity
used for Linear lookup. Migrated legacy files may also carry
`provider_project_slug`; that field is an explicit compatibility fallback for
older slug-based tracker configuration and is not a repository association or
execution default. During routing, a supplied project ID or slug is selected
when it matches an active project key; this lets a stale ID fall back to a
valid active provider slug without choosing a repository. Surrounding
whitespace is trimmed before project IDs and slugs enter the routing indexes.
### Repository binding
In `project_set` mode, each terminal child task must carry exactly one managed
`repo:<alias>` label. The alias resolves through the central repository
inventory to a provider-qualified canonical repository ID and a credential-free
remote fingerprint. A project's `repositories` list constrains the aliases
that are valid for its tasks; it never selects a default. Parent tasks remain
repository-neutral and must not carry a managed repository label.
When a remote exposes an authority such as `github.com` or a GitHub Enterprise
host, that authority is included with the provider-native ID in both the
canonical repository ID and safe fingerprint; this prevents two provider
installations from colliding while remaining stable across rename or transfer.
Missing, unknown, duplicate, parent, out-of-scope, and disallowed bindings are
retained as distinct scheduler routing outcomes and do not create workspaces.
An empty managed label such as `repo:` remains visible to strict validation and
is rejected as an invalid binding rather than being treated as an absent label.
The resolved binding records the central config and inventory generations
before a worker is claimed. A binding change on a claimed task stops and
removes the old generation's workspace before materializing the replacement,
and fences late worker events from the old generation. A binding change on a
queued retry removes its stale workspace while preserving the retry entry in
the replacement workspace or in the instance retry-state root when the new
binding is blocked. A recovered worker is stopped and acknowledged before an
unproven workspace is removed. A
legacy workspace with no issue binding may be backfilled only when its
persisted issue, run, or after-create receipt metadata proves the requested
repository; the current legacy configuration alone is not historical proof.
Unproven in-flight recovery is rematerialized through the normal retry path. In `legacy_single` mode only, an unlabelled task resolves to
the configured repository for compatibility.
Generated planning front matter quotes repository aliases as YAML strings, and
sub-issue regeneration moves a parent's binding to the generated terminal
children while clearing it from the new parent; when the parent is neutral,
existing child bindings are retained by child position during regeneration.
Task-package conversion rejects explicitly blank repository aliases in every
routing mode while continuing to accept unlabelled tasks in `legacy_single`.
Task-package `routingMode` must be a scalar `legacy_single` or `project_set`
value; malformed YAML types are reported as ordinary package validation
errors. The planning compiler emits `project_set` plus the sorted
`repositoryAliases` inventory whenever terminal bindings are present, so
compiled task packages retain the planning artifact's explicit routing mode and
trusted `repositoryAliases` inventory through publication, even when a
malformed strict plan has not yet assigned bindings to its terminal tasks; the
converter then rejects the missing bindings instead of downgrading the package
to legacy dispatch.
Every configured and task-level alias must remain non-empty after trimming.
The Rust manifest validator applies the same strict cardinality and inventory
checks, including rejecting multi-alias list forms before a package can be
accepted. During publication, existing Linear child presence is checked before
adding a repository label so removed package children cannot leave a bound
parent behind. Gateway task-graph and run-detail blockers preserve the typed
repository-binding reason for operators.
An explicitly configured but blank `remote.provider_id` is rejected rather
than falling back to the mutable repository locator for canonical identity.
Issue regeneration retains terminal-child bindings by position and keeps the
regenerated parent repository-neutral.
## Configuration migration
Migration is explicit and staged:
```bash
opensymphony migrate preflight --repo /path/to/repo
opensymphony migrate apply --repo /path/to/repo --config /path/to/repo/config.yaml
opensymphony migrate rollback --config /path/to/repo/config.yaml
```
`preflight` is read-only and reports recognized workflow fields, clone-hook
risks, and secret/remote-risk booleans without printing their values. `apply`
backs up the legacy config and workflow, writes central config and a reduced
workflow body through same-directory staging, preserves supported repository-local
`codex`/`logging` namespaces, and records an activation marker specific to the
central config destination. A marker is written after validation and staging but
before replacement so an interrupted apply remains recoverable. Relative legacy
workspace roots are resolved against the target repository, and migration
requires an exact `Target branch:` line.
Applying again with a separate `--output` detects the active destination
generation before creating a backup or rewriting the source. `rollback`
restores the backup and refuses to run while the instance's strict-run marker
is active; it restores the original file permissions as well as file contents.
Repeating a complete `apply` is a no-op; a partially published activation
promotes its staged workflow or restores the backup before retrying.
When preserving a legacy `.opensymphony/memory` tree, preflight inspects the
legacy inputs without requiring memory quiescence and does not copy or write
files. Apply, direct CLI memory writers,
automatic capture, archive, and the local memory server claim the same atomic
coordination lock; the server holds it for its lifetime while publishing an
activity marker. Owner PIDs allow stale lock and marker recovery after an
unclean exit; apply removes stale markers only after it owns the lock. Rollback
also fingerprints the migrated catalog and refuses to restore the legacy
generation after post-migration memory has changed, preserving that evidence.
Central-config runs publish a destination-hashed
`.opensymphony/migration/strict-run-<destination>.active` marker for their full
process lifetime; rollback claims the same marker before restoring the legacy
generation, so startup and rollback cannot interleave, and normal shutdown
removes it. Stale markers are reclaimed only when their owner PID is no longer
live. Recovery treats a terminal successful run as
successful even when its retry count reached the configured limit, while a
pending retry is parked if a lowered limit would make it exceed the current
budget. Failed interrupt requests keep the execution owned until a later
reconciliation observes a stop acknowledgement, and retained failed
workspaces are not force-removed during terminal recovery. Durable run
diagnostics are redacted before `run.json` is written. A file containing the
central-only `memory.catalog_root` shape is classified as central even if its
required routing fields are malformed, so it fails closed instead of falling
back to legacy parsing.
When the migrated implementation prompt itself begins with `---`, migration
emits an empty front-matter boundary so the prompt remains implementation text
on the next load.
## Bootstrap
Use `opensymphony init` from the target repository root:
```bash
cd /path/to/target-repo
opensymphony init
```
`opensymphony init` is the primary setup path for existing repositories. It:
- fetches the current starter files from the template repo's raw GitHub URLs
- copies missing files into the target repo
- leaves an existing `AGENTS.md` untouched and writes starter guidance to
`AGENTS-example.md` during first-time setup
- prompts before overwriting other conflicting files
- fills the `WORKFLOW.md` clone hook from `git remote` when possible
- offers to fill the Linear project slug/key in `WORKFLOW.md`
- records the feature PR and sync target branch in `WORKFLOW.md` under
`## Branch target`; the default is `develop`, and `--target-branch main` or
`--target-branch release/next` can set another local branch name
- creates or updates `.gitignore` so local OpenSymphony runtime state stays untracked
- can optionally scaffold OpenHands AI PR review
- can configure the GitHub Actions variables, label, and optional review secret
automatically when `gh` is installed and can access the repository
- prompts whether to commit and push the generated OpenSymphony files so shared
skills and, when selected, AI PR Review setup are present in the remote
repository before story work starts
For repositories that are already initialized, `opensymphony update` is the
maintenance path for template-owned skills:
```bash
cd /path/to/target-repo
opensymphony update
```
The command first checks whether the installed CLI is older than the newest
published `opensymphony` release and only runs `cargo install opensymphony --locked`
when it actually needs to. If the current directory already looks like an
OpenSymphony target repo because it has both `WORKFLOW.md` and `config.yaml`,
the command then refreshes changed or new files under `.agents/skills/`.
Upgrades from a CLI older than 2.11 must first satisfy the Rust 1.97.1 minimum;
the one-time `cargo +stable` recovery command is documented in
[Operations](operations.md).
When `--target-branch` or `--code-review` is present, `update` uses workflow
settings mode instead of the normal maintenance path. It requires `WORKFLOW.md`
and `config.yaml`, patches the managed workflow markers, rewrites known legacy
branch-control phrases when the target branch changes, and skips Cargo
self-update, template skill refresh, and memory bootstrap:
```bash
opensymphony update --target-branch develop
opensymphony update --target-branch main
opensymphony update --target-branch release/next
opensymphony update --target-branch release/next --code-review openhands
```
The target-branch marker is also the source of truth for persistent Code Graph
indexing. `POST /api/v1/code/repos/{repo_id}/index` and
`code_index_repo` resolve that branch server-side; they do not accept a client
path. If the marker is absent, the indexer uses `develop`. Ensure the selected
branch is available as `origin/<branch>` or a local branch before indexing.
The template repository is still the upstream source of those starter assets,
but it is an implementation detail of `opensymphony init`, not a required
manual setup step:
- [kumanday/OpenSymphony-template](https://github.com/kumanday/OpenSymphony-template)
- [Raw template base](https://raw.githubusercontent.com/kumanday/OpenSymphony-template/refs/heads/main/WORKFLOW.md)
Fresh init branch-target behavior is fully consistent only when that template
repo's `WORKFLOW.md` and `pull`/`push`/`land` skills have the same marker-aware
wording as this repository's local copies.
## Files Added By `init`
Core bootstrap payload:
- `WORKFLOW.md`
- `AGENTS.md`
- `AGENTS-example.md` when `AGENTS.md` already existed before first-time setup
- `config.yaml`
- `.gitignore` created or updated to ignore OpenSymphony runtime state
- `.agents/skills/` copied recursively, including skill-local `references/`, `scripts/`, and similar helper files
- `.agents/skills/linear/references/`
- `.github/CODEOWNERS`
- `.github/pull_request_template.md`
## Refreshing Template Skills
Without workflow-setting flags, `opensymphony update` only refreshes
template-managed files under `.agents/skills/`.
It does not:
- rerun the interactive `init` prompts
- modify `WORKFLOW.md`
- merge or rewrite `AGENTS.md`
- create `AGENTS-example.md` after `config.yaml` exists
- copy `.github/*` bootstrap files
- delete repo-local extra skills that are not in the template tree
Optional AI PR review scaffolding, controlled by the review provider choice
(`--review-provider <openhands|codex|none>` or the interactive prompt):
- `openhands`: `.github/workflows/ai-pr-review.yml` and
`.agents/skills/custom-codereview-guide.md`
- `codex`: `.agents/skills/custom-codereview-guide.md` only — reviews run
through the Codex GitHub integration with a ChatGPT subscription, so no
Actions workflow, secret, or label is scaffolded. `init` prints the
one-time browser setup checklist; see
[codex-code-review-setup.md](codex-code-review-setup.md).
The chosen provider is recorded in `WORKFLOW.md` as
`Active review provider:` under `## Automated AI PR review`, which tells
agents how to re-trigger review after follow-up pushes (`review-this` label
for openhands, an exact `@codex review` comment for codex).
For initialized target repos, `opensymphony update --code-review openhands`
updates the marker and attempts to enable an existing
`.github/workflows/ai-pr-review.yml` through `gh workflow`. It does not create
or repair that workflow when the file is missing. Switching with
`--code-review codex` or `--code-review none` records the marker and attempts
to disable an existing OpenHands review workflow. If `gh` is unavailable,
unauthorized, or cannot access Actions, `update` warns and leaves the workflow
state unchanged; verify or adjust it manually.
## Labels
If you choose the `openhands` review provider and `gh` is available with
repository access, `opensymphony init` can create the `review-this` label for
you. If automation is skipped, create it once per repository:
```bash
gh label create "review-this" --description "Trigger AI PR review" --color "d73a4a" --force
```
The `codex` provider does not use the `review-this` label.
## Review The Generated Workflow
After `init`, review `WORKFLOW.md` and `config.yaml`.
If you accept the final commit/push prompt, `init` stages only the files it
created or updated, commits them as `chore: bootstrap OpenSymphony`, and pushes
`HEAD` to the detected git remote. If the repository already has staged changes
or no single remote can be detected, `init` leaves git alone and prints a
reminder to commit and push manually.
Important fields:
| `tracker.project_id` | Linear `Project.id` used to resolve the provider project before issue polling | - | `2b7c...` |
| `tracker.project_slug` | Linear `Project.slugId` from the project URL | - | `my-project-5250e49b61f4` |
| `WORKFLOW.md` `Target branch:` | Local branch name agents use as `origin/<target-branch>` for syncs and PR bases | - | `develop`, `main`, `release/next` |
| `workspace.root` | Where to store per-issue workspaces | - | `~/.opensymphony/workspaces` |
| `routing.*_env` | Optional environment-variable selectors for harness, model, and model profile | `OPENSYMPHONY_*` | `MY_HARNESS` |
| `memory.token_env` | Name of the environment variable used by the memory service | `OPENSYMPHONY_MEMORY_TOKEN` | `MEMORY_TOKEN` |
| `openhands.conversation.agent.llm.model` | LLM model to use | `LLM_MODEL` | `openai/accounts/fireworks/models/glm-5p1` |
| `openhands.conversation.agent.llm.credential_mode` | LLM credential adapter | - | `api_key` or `openai_subscription` |
For Linear trackers, `tracker.project_slug` should store the project's
`slugId`, not a `team/project` path.
## Environment Variables
OpenSymphony uses standard OpenHands environment variable names.
Fireworks example via the OpenAI-compatible provider adapter:
```bash
export LLM_MODEL="openai/accounts/fireworks/models/glm-5p1"
export LLM_API_KEY="fw-..."
export LLM_BASE_URL="https://api.fireworks.ai/inference/v1"
```
The gateway also exposes the local model settings seam through
`GET /api/v1/model-settings`. The default API-compatible profile maps to the
same three environment variables:
- `LLM_MODEL` identifies the configured model string.
- `LLM_API_KEY` is exposed only as a credential reference.
- `LLM_BASE_URL` identifies the optional OpenAI-compatible base URL.
Subscription-backed model profiles are represented as credential references for
local keychain storage, isolated OpenHands auth-directory storage, and future
hosted broker storage. Those references are safe to render in clients because
they do not contain raw API keys, OAuth access tokens, or refresh tokens.
For the Codex app-server harness, OpenSymphony represents the local ChatGPT
subscription as a Codex CLI login reference:
- `profile.id`: `codex-chatgpt-local-keychain`
- `credential_reference.kind`: `codex_cli_login`
- `credential_reference.reference`: `codex-cli:chatgpt-login`
- `storage_mode`: `codex_cli_home`
This reference tells clients and operators that readiness is owned by the
installed Codex CLI. OpenSymphony checks readiness with `codex --version`,
`codex app-server --help`, and `codex login status`; it does not read private
Codex credential files and does not copy OAuth access or refresh material into
workspaces, workflow files, logs, Linear comments, or browser payloads. Gateway
checks are cached briefly in process to avoid spawning Codex subprocesses for
every client poll, and each Codex CLI check has a bounded timeout so a stalled
local login probe reports an unknown/non-ready state instead of blocking the
gateway request.
The `codex_local_readiness` field on `GET /api/v1/model-settings` reports:
- whether the Codex CLI command is installed and runnable,
- whether the app-server surface is available,
- whether `codex login status` reports `Logged in using ChatGPT`,
- explicit logged-out, expired, unsupported, permission-denied, or unknown
states,
- safe operator commands for login (`codex login --device-auth`), status
(`codex login status`), and logout (`codex logout`).
The current classifier treats `Logged in using ChatGPT` and
`Logged in with ChatGPT` from `codex login status` as ready. It renders
logged-out, expired, unsupported, permission-denied, and unknown outputs as
non-ready status states rather than guessing or reading private credential
files.
Default OpenAI model profiles use `gpt-5.5` for API-compatible and
subscription-backed entries. Existing saved desktop or web profiles remain
unchanged until an operator edits them.
Harness and model selection are configured with the alpha `routing`
front-matter section. When omitted, `opensymphony run` keeps the default
`openhands_agent_server` harness and the OpenHands LLM settings from the
workflow.
```yaml
routing:
harness: codex_app_server
model: gpt-5.5
model_profile: codex-chatgpt-local-keychain
```
The same selected values can be supplied by a launcher or desktop shell through
environment variables:
- `OPENSYMPHONY_HARNESS`
- `OPENSYMPHONY_MODEL`
- `OPENSYMPHONY_MODEL_PROFILE`
When `routing.harness` is `openhands_agent_server`, a selected `routing.model`
or `OPENSYMPHONY_MODEL` becomes the OpenHands conversation LLM model. When
`routing.harness` is `codex_app_server`, a selected model is passed to Codex
`thread/start`, `thread/resume`, and `turn/start`; `thread/archive` is used
only to roll back a newly created thread if its first manifest cannot be
persisted. If no model is selected, OpenSymphony omits the model and lets the
Codex CLI/app-server use its own default from Codex configuration such as
`~/.codex/config.toml`. Codex-only routing does not resolve OpenHands LLM
environment variables or launch the managed OpenHands server.
Local Codex execution uses a full-automation profile. OpenSymphony launches the
installed Codex CLI as
`codex --dangerously-bypass-hook-trust app-server --stdio`, validates
`initialize`, `thread/start`, `thread/resume`, the rollback `thread/archive`,
and `turn/start` against the schema generated by that installed CLI, creates
the thread with `approvalPolicy: "never"` and `sandbox: "danger-full-access"`,
then starts the task turn with
`approvalPolicy: "never"` and `sandboxPolicy: { "type": "dangerFullAccess" }`.
If the installed Codex schema rejects those fields, update Codex before running
the Codex harness.
Set `opensymphony run --dry-run` to preview the selected harness/model without
launching a model-backed worker. The selected harness must still be available
and able to start runs.
For local Codex stdio execution, `OPENSYMPHONY_CODEX_BIN` may point to an
alternate Codex binary in trusted operator environments only; it is not a
hosted-mode tenant input.
OpenAI ChatGPT/Codex subscription credentials are available only when
OpenSymphony is built with the `openhands-subscription-credentials` Cargo
feature. The workflow stores environment-variable names and auth-directory
references, not token values. The short-lived access token should be established
through the documented OpenHands SDK login flow, such as browser login or
device-code login, and exposed to the orchestrator through the configured
environment reference:
```yaml
openhands:
conversation:
agent:
llm:
model: gpt-5.2-codex
credential_mode: openai_subscription
subscription:
vendor: openai
access_token_env: OPENHANDS_OPENAI_SUBSCRIPTION_ACCESS_TOKEN
account_id_env: OPENHANDS_OPENAI_SUBSCRIPTION_ACCOUNT_ID
auth_directory_env: OPENHANDS_AUTH_DIR
auth_method: device_code
open_browser: false
```
In subscription mode, OpenSymphony constructs the same OpenAI/Codex LLM request
shape documented by the pinned OpenHands SDK: `openai/<model>`,
`https://chatgpt.com/backend-api/codex`, official Codex headers,
`litellm_extra_body.store=false`, and streaming enabled. Refresh tokens remain
in the selected credential store and must not be copied into workspaces,
workflow files, logs, Linear comments, or browser payloads.
The `auth_directory_env`, `auth_method`, `open_browser`, and `force_login`
fields describe how the subscription credential was established by the SDK or a
future broker. They are retained in the launch profile for diagnostics and UI
status, but OpenSymphony does not forward them as undocumented agent-server
conversation fields. Only the short-lived access token reference is resolved
when building the OpenHands conversation request.
### Local Codex And Subscription Testing
The local Codex app-server stdio harness is compiled into normal OpenSymphony
builds. OpenHands ChatGPT/Codex subscription adapter tests remain
feature-gated. Use the smallest feature set for the path you are exercising:
```bash
cargo check-system-duckdb \
--features openhands-subscription-credentials
cargo test-system-duckdb \
--features openhands-subscription-credentials \
subscription -- --nocapture
cargo test-system-duckdb --test codex_app_server
```
The old `codex-app-server-prototype` feature has been removed; local stdio
harness capability, lifecycle, normalization, and benchmark checks run through
normal OpenSymphony builds.
To install a local `opensymphony` binary with subscription credentials enabled
while using the system DuckDB development path:
```bash
export DUCKDB_LIB_DIR="/opt/homebrew/opt/duckdb/lib"
export DUCKDB_INCLUDE_DIR="/opt/homebrew/opt/duckdb/include"
export DYLD_LIBRARY_PATH="$DUCKDB_LIB_DIR${DYLD_LIBRARY_PATH:+:$DYLD_LIBRARY_PATH}"
cargo install --path . --no-default-features \
--features duckdb-prebuilt,openhands-subscription-credentials
```
For a local subscription-auth smoke test, establish the OpenAI ChatGPT/Codex
subscription credential with the documented OpenHands SDK browser or device-code
login flow, then export only the short-lived token and optional account identity
that your workflow references:
```bash
export OPENHANDS_OPENAI_SUBSCRIPTION_ACCESS_TOKEN="<short-lived-access-token>"
export OPENHANDS_OPENAI_SUBSCRIPTION_ACCOUNT_ID="<optional-account-id>"
export OPENHANDS_AUTH_DIR="$HOME/.openhands/auth"
```
Then set `credential_mode: openai_subscription` in `WORKFLOW.md` as shown above
and run `opensymphony run` with the feature-enabled binary. Do not store OAuth
JSON files, refresh tokens, or access tokens in the repository, issue
workspaces, Linear comments, or browser-visible payloads.
For manual verification of the pinned OpenHands SDK OAuth behavior, run the SDK
login flow in the managed OpenHands virtual environment. Use a temporary `HOME`
when you want the probe to keep OAuth credentials out of your normal
`~/.openhands/auth` directory:
```bash
cat > /tmp/openhands_subscription_probe.py <<'PY'
import os
from openhands.sdk import LLM
llm = LLM.subscription_login(
vendor="openai",
model=os.environ.get("OH_SUBSCRIPTION_MODEL", "gpt-5.2-codex"),
auth_method=os.environ.get("OH_AUTH_METHOD", "device_code"),
open_browser=False,
force_login=os.environ.get("OH_FORCE_LOGIN", "0") == "1",
)
headers = llm.extra_headers or {}
print("subscription:", getattr(llm, "_is_subscription", False))
print("model:", llm.model)
print("base_url:", llm.base_url)
print("stream:", llm.stream)
print("has_api_key:", bool(llm.api_key))
print("header_keys:", sorted(headers.keys()))
print("has_chatgpt_account_id:", "chatgpt-account-id" in headers)
print("litellm_extra_body:", llm.litellm_extra_body)
PY
cd ~/.opensymphony/openhands-server
export OH_SPIKE_HOME=/tmp/opensymphony-openhands-subscription-spike
rm -rf "$OH_SPIKE_HOME"
mkdir -p "$OH_SPIKE_HOME"
OPENHANDS_SUPPRESS_BANNER=1 \
HOME="$OH_SPIKE_HOME" \
OH_FORCE_LOGIN=1 \
OH_AUTH_METHOD=device_code \
uv run python /tmp/openhands_subscription_probe.py
```
The device-code flow may require enabling **Security and login -> Enable device
code authorization for Codex** in ChatGPT settings:
Successful output should show `subscription: True`, model
`openai/gpt-5.2-codex`, base URL `https://chatgpt.com/backend-api/codex`,
`has_api_key: True`, `has_chatgpt_account_id: True`, and
`litellm_extra_body: {'store': False}`. The cached OAuth file for this isolated
probe is written to:
```text
/tmp/opensymphony-openhands-subscription-spike/.openhands/auth/openai_oauth.json
```
This SDK credential cache is not the same thing as
`~/.opensymphony/openhands-server`. The latter is OpenSymphony's managed
OpenHands tool installation and conversation workspace. The SDK auth cache is
where OpenHands stores ChatGPT OAuth credentials by default. Current
OpenSymphony subscription support validates and forwards a subscription-shaped
LLM configuration, but it does not yet provide an operator-facing command that
logs in, refreshes, and injects those credentials automatically.
The workflow supports `${VAR}` syntax for environment variable substitution in
the front matter:
```yaml
openhands:
conversation:
agent:
llm:
model: ${LLM_MODEL}
```
## Conversation Condensation
Optional conversation condensation is enabled by default per workflow to reduce
long-history context pressure before the agent-server hits the model window:
```yaml
openhands:
conversation:
agent:
condenser:
max_size: 240
keep_first: 2
```
OpenSymphony forwards an OpenHands `LLMSummarizingCondenser` that reuses the
conversation agent's LLM settings. The condenser is enabled by default with
`max_size: 240` and `keep_first: 2`. To disable it, set `enabled: false`.
## Runtime Config
`opensymphony init` also copies a starter `config.yaml` next to the target
repository `WORKFLOW.md`.
Minimal local-supervised example:
```yaml
control_plane:
bind: 127.0.0.1:2468
openhands:
tool_dir: ~/.opensymphony/openhands-server
memory:
auto_capture: true
auto_archive: false
```
The bind address is the single local HTTP surface for both the gateway API used
by the web/desktop clients (`/api/v1/capabilities`,
`/api/v1/dashboard/snapshot`, and related `/api/v1/*` routes) and the
control-plane compatibility routes used by the TUI (`/healthz`,
`/api/v1/snapshot`, and `/api/v1/control/events`).
Provision that app-managed directory with:
```bash
opensymphony install openhands
```
For managed local OpenHands, OpenSymphony derives a repository-scoped
conversation store from `openhands.tool_dir` and the target repo path:
```text
<tool_dir>/workspace/conversations/repos/<repo-key>/
active/
archived/
```
`opensymphony run` first moves known terminal issue conversations from existing
workspace manifests into `archived/`, then prepares `active/` from current
Linear candidate issue manifests before launching the managed server with
`OH_CONVERSATIONS_PATH` pointing at `active/`. The terminal-workspace sweep is a
temporary compatibility shim for older flat stores. This keeps completed or
manually archived issue history out of normal server startup while preserving it
for `opensymphony debug`.
When your workflow points at an external OpenHands agent-server with
`openhands.transport.session_api_key_env`, `config.yaml` can omit
`openhands.tool_dir`.
Use [examples/target-repo/config.yaml](../examples/target-repo/config.yaml) as
the starting template if you want to inspect the checked-in example.
[examples/configs/local-dev.yaml](../examples/configs/local-dev.yaml) is a
developer-facing doctor fixture for this repository. It is not the runtime
config that `opensymphony run` looks for in a target repo.
## Planning Workspace
The planning workspace is a dense, editable, review-oriented UI for the
hosted-client mode. It renders from the local planning workspace state and is
intended to feel like a task-creation tool with Linear as the publishing
target.
### Intentional MVP limitations
- The fixture planning session is intentionally reused across project switches
in the local app shell. The workspace is not yet keyed per project, so
switching projects keeps the same conversation, artifacts, and hierarchy
until the gateway provides real planning sessions or a per-project session
loader is implemented. This is documented behavior, not a bug.
## Memory Configuration
Project memory stores runtime state under `.opensymphony/memory` and can be
captured automatically by `opensymphony run`. Runtime automation is controlled
by `config.yaml`:
```yaml
memory:
auto_capture: true
auto_archive: false
```
`auto_capture` defaults to `true`. It captures terminal issue transitions
observed by the run loop. `auto_archive` defaults to `false`; when enabled, it
archives only after successful capture with no blocking warnings.
When archive succeeds and the repo uses the managed local OpenHands server,
OpenSymphony also moves the issue's persisted conversation from the repo-scoped
`active/` store to `archived/`.
When `memory.serve` uses the default `127.0.0.1:0` bind, the first successful
run records the selected loopback address in
`<workspace-root>/.opensymphony-memory-bind.json`. Later daemon starts reuse
that exact address so a recovered parent conversation keeps the memory endpoint
associated with its restored bearer. If the recorded port is unavailable or
the configured interface changes, startup fails instead of silently assigning
a different endpoint. An explicit nonzero `memory.bind` remains unchanged.
Initialize the shared memory policy and learned ontology file with:
```bash
opensymphony memory init
```
This creates `.opensymphony/memory/memory.yaml` and updates `.gitignore` so only
that shared config is tracked. Capsules, markdown indexes, DuckDB, source
snapshots, and runtime logs remain local:
```text
.opensymphony/memory/
memory.yaml
issues/
indexes/
memory.duckdb
```
`memory.yaml` contains policy plus learned structure. `memory init` seeds stable
areas from existing top-level `docs/*.md` files when present; otherwise it
starts with an empty `areas` map and capture evolves it from Linear and PR
narrative evidence:
```yaml
memory_root: .opensymphony/memory
visibility: private
index_path: .opensymphony/memory/memory.duckdb
confidence_threshold: 75
markdown_indexes: true
code_intel:
enabled: true
ast:
enabled: true
max_file_bytes: 2097152
max_files_per_request: 200
max_matches_per_request: 2000
max_capture_bytes: 4096
docs:
public_root: docs
default_visibility: public
deny_private_links: true
areas:
openhands-runtime:
title: OpenHands Runtime
docs_target: docs/openhands-runtime.md
visibility: public
status: stable
confidence: 85
aliases:
- OpenHands Runtime
source_refs:
docs:
- docs/openhands-runtime.md
linear_labels:
- runtime
```
`code_intel.ast.max_file_bytes`, `max_files_per_request`,
`max_matches_per_request`, and `max_capture_bytes` bound AST reads, query
results, and rendered snippets. Generated, vendor, build, and cache directories
(`.git`, `node_modules`, `target`, `dist`, `build`, `.venv`, `__pycache__`,
`coverage`, `.next`, `.turbo`, `vendor`, and `generated`) are skipped with
trace warnings during directory traversal; explicitly requested files inside
them can still be parsed when they pass path containment and resource limits.
Private memory should stay out of source control. Commit
`.opensymphony/memory/memory.yaml` and generated public docs when appropriate;
do not commit issue capsules, markdown indexes, DuckDB, source snapshots, or
runtime state.
## OpenHands PR Review
If you opt into OpenHands PR review during `init`, the CLI will try to
configure the GitHub Actions variables, label, and optional review secret for
you when:
- `gh` is installed
- `gh` can access the target repository
- you approve the automation prompt
If any of those are missing, `init` falls back to a short checklist plus the
manual `gh` commands. The full verification and branch-protection guidance
lives in the OpenSymphony docs at
[ai-pr-review-human-setup.md](ai-pr-review-human-setup.md); `init` does not
copy that guide into the target repository.
## ACP stdio profiles
Workflow front matter and central configuration accept the same typed `acp.profiles`
map and `routing.harness_profile` selector:
```yaml
routing:
harness: acp
harness_profile: local
acp:
profiles:
local:
command: /absolute/path/to/agent
args: [acp]
transport: stdio
protocol_versions: [1]
env_refs:
AGENT_API_KEY: OPERATOR_AGENT_API_KEY
auth:
method_id: agent_login
permissions:
mode: operator
```
`permissions.mode` defaults to `operator`, which waits for a live operator
response. `deny` selects an offered `reject_once` option; `allow_once` selects
an offered `allow_once` option for trusted unattended profiles. If the agent
does not offer the configured kind, the callback is cancelled. Neither policy
invents an option ID or grants lasting access. Operator-mode runs require an
attached response path and use the callback deadline configured by the ACP
client limits.
Central configuration migration transfers `routing.harness_profile` and the full
`acp.profiles` map from the legacy workflow before rewriting its prompt body.
Environment references remain names throughout migration. At launch, each source
variable is removed from the child environment unless that name is also an
explicit target in `env_refs`; only the intended credential aliases are passed.
The executable ACP APIs are `opensymphony_acp::SessionHost` for retained sessions
and `opensymphony_acp::run_turn` for one-turn compatibility. Host callers supply
an explicit `RetentionPolicy`: defaults are eight sessions, 15 minutes idle
retention, 60-second renewable attachment leases, and 16 leases per session.
Active prompts and leases pin the process; capacity exhaustion refuses a new
launch. These host API settings are independent of profile protocol capabilities.
`SessionLaunch::require_persistence` rejects peers without negotiated load/resume
support. The caller supplies a non-secret credential/grant revision and the
scheduler's exact workspace identity; changes prevent session reuse.
Production `opensymphony run` selects this profile through the scheduler and
persists the effective route under the workspace metadata directory. Recovery
uses the route bound to the prepared `run.json` record even when the current
default profile differs. If `routing.model` is unset, preparation resolves the
profile's `session.model` into that route and the runtime envelope. Older run
records may use the workspace route snapshot
only when the durable ACP identity matches their run ID and attempt. A finished ACP
turn reconciles a recovered run only when its durable run ID and attempt match;
a newly prepared attempt submits its own prompt. ACP-only execution
does not start an OpenHands server. Production retains at most 128 ACP sessions;
the scheduler continues to enforce `agent.max_concurrent_agents`. Select a
different profile only after the retained session can retire safely; uncertain
submissions remain fenced. The same profile ID starts a fresh owner when its
effective command, arguments, session options, host services, or resolved
credential scope changes.
Credential source names follow the host platform's environment-name rules;
Windows aliases differing only in ASCII case resolve to the same credential
when checking whether a retained owner must rotate.
Managed memory run ID, attempt and project-set values are part of that scope;
when they change, the retained ACP process is replaced so its environment
matches the active run. ACP memory prompt guidance uses the scoped worker
overlay that supplies the managed memory attachment.
Central profiles remain authoritative over repository-local workflow files.
Profile shape is validated at central load with the profile ID and specific
validation cause. Harness/profile selection and model restrictions are validated
after workflow environment overrides resolve. An explicit harness environment
override to another harness clears the ACP selector; an override to ACP retains
it. Windows environment references
use case-insensitive variable names; a resolved alias replaces inherited target
values regardless of their casing. Configured target names must themselves be
distinct under host name rules; Windows rejects case-equivalent `env_refs` targets
before launch, while POSIX preserves case-distinct variables.
Profile arguments are literal argv entries, never shell templates. `env_refs`
contains variable names; resolved values stay in the host-owned launch context.
Profile preflight evaluates the resolved worker environment, including Linear
client-credentials overrides, with the same precedence used at launch. References
to checkout-only credential variables are unavailable to ACP profiles, including
when an ambient value happens to exist. Unrelated non-UTF-8 ambient variables
are ignored when assembling the launch environment.
The selected authentication method must be an advertised agent-handled method;
terminal/browser authentication is not advertised. Omit `auth` for agents with
existing login state that need no `authenticate` call.
Profiles reject cwd overrides, unsupported wire versions/transports, unregistered
extensions, credential arguments regardless of flag casing, and invalid environment
references. Optional
`required_capabilities` supports `prompt.image`, `prompt.audio`, and
`prompt.embedded_context`; each requirement is checked before session creation,
and a failed check names the missing capability.
`extensions` accepts `fixture_echo@1` for executable outbound tests and
`cursor@2026.09.08-6caf4ff` for the pinned CLI's observed plan approval and
todo request contracts. Cursor callbacks bind to the connection-owned active
session even when the peer omits `sessionId`. The registration does not enable
unobserved question, task, or image methods. Duplicate IDs and unspecified
vendor versions fail validation.
Registration alone grants no operation: outbound use also requires the peer's
capability predicate and an active, bound run.
The prompt API sends text. Explicit session selections live in each profile:
```yaml
session:
model: model-id
mode: code
options:
thought-level: high
```
`session.model` and `session.mode` select advertised config options by category;
`session.options` selects by exact option ID, including grouped select values.
The client applies choices before every prompt, including retained turns,
validates the returned complete option list, and consumes subsequent config and
mode updates. Currently supported
model/mode prerequisites apply before dependent options, using the refreshed
advertisements after each response. Legacy
`session/set_mode` is used when the peer supplies modes without config options.
Unsupported explicit choices fail setup. Boolean options and legacy experimental
model RPCs are not advertised. `routing.model` and its configured environment override select an ACP model ID
and take precedence over `session.model`. OpenHands `routing.model_profile` is
rejected for ACP.
The negotiated run capability reports model selection when the bound ACP
session advertises a selectable model option; it updates if that capability
changes before a retained prompt.
The host supplies `LaunchContext.services: HostServices`. Its `read_files`,
`write_files`, and `terminals` flags default to false and enable only the matching
implemented callbacks. `mcp_servers` contains resolved host-owned scoped MCP
attachments: stdio is baseline support, while HTTP and SSE require the peer's
advertisement. Every supplied server is required; unsupported transports fail
before session creation. Existing memory grants can be passed as an HTTP server
named `opensymphony-memory` with the issued Authorization header. Resolved values
stay out of the profile. Every stdio MCP argument value is structurally masked
in captured requests; credential option values in separate and equals forms,
including generic header values, are also redacted from echoed events and
stderr. The peer receives the exact host-supplied attachment. ACP operator
responses use the scheduler-owned pending request path; arbitrary vendor
extensions remain separately gated.
The gateway publishes each registered outbound operation's parameter and
result schemas, version, capability predicate, deadline, and effect policy in
profile and negotiated run capabilities. Clients invoke one through
`POST /api/v1/actions/dispatch` with `action_kind: harness_operation`, a run
target, and exactly `run_id`, `operation_id`, and `arguments` in the payload.
Use `harness_capability.run_binding_id` from the current run detail or snapshot
as `run_id`; the gateway and scheduler reject stale attempts. The owner resolves
the wire method and session ID. At most eight outbound operations are outstanding
per ACP session, and completion or failure is published to the event journal
with the action correlation ID. The action rejects an
idempotency key so replay cannot silently repeat an uncertain operation.
ACP credential arguments such as `--access-token`, `--oauth2-bearer`,
`--client-secret`, and `--pat` are rejected in separate-value and equals forms,
including mixed case; credentials belong in `env_refs`. A top-level `acp` section
selects the central configuration parser, so incomplete central files fail
validation before legacy defaults can be applied.
ACP callback text is bounded by both its facility limit and the complete encoded
response budget, including JSON escaping and the request ID. A file response that
does not fit returns a callback parameter error; terminal output retains a UTF-8
tail and reports truncation. Scoped HTTP/SSE MCP endpoints must use HTTP or HTTPS
without URL userinfo, fragments or query strings; pass resolved grants in headers.
MCP attachments cannot include resolved excluded checkout credentials, including
values aliased under another environment name, header or argument. Filesystem
contents and terminal output remain intact on the wire and are structurally
redacted from source history and evidence. Model and mode categories are
resolved from each refreshed option list so prerequisite selections can reveal
dependent options.
## Qualified ACP profiles
The [live qualification matrix](acp-live-qualification.md) gives pinned Cursor
and Devin versions and executable test commands. A new compliant stdio profile
uses the `routing.harness: acp` and `routing.harness_profile` keys shown
above, with `command`, `args`, and optional `env_refs`; no vendor-specific
scheduler code is needed. Profile preflight checks configuration and
executable availability. Authentication, session load, modes, options, and
extensions are reported from the negotiated live session. The pinned Cursor
extension registration is limited to the observed plan and todo request
methods.
## Current model
- COE-252 contributed: PR #10: Implement foundation workflow and scheduler contracts
- COE-253 contributed: PR #19: COE-253: OpenHands Runtime Adapter (merge `911b0b4`)
- COE-254 contributed: PR #6: COE-254: bootstrap tracker, workspace, and orchestration core
- COE-255 contributed: PR #4: COE-255: add control plane and FrankenTUI slice
- COE-256 contributed: PR #1: COE-257: tighten hosted deployment guidance
- COE-258 contributed: PR #83: Add memory init and mapped docs sync
## Important invariants
- Preserve the behavior described in the recent captured changes unless current code and tests show it has changed.
- Use capsule source refs to inspect the original PR or Linear issue when context is ambiguous.
## Operational flow
- No generated diagram requested for this sync.
## Known gotchas
- No area-specific gotchas were inferred from the selected memory.
## Recent changes
- COE-252: Foundation and Contracts
- COE-253: OpenHands Runtime Adapter
- COE-254: Tracker, Workspaces, and Orchestration
- COE-255: Observability and FrankenTUI
- COE-256: Validation and Local Operations
- COE-258: Bootstrap workspace and crate boundaries
- COE-259: Workflow loader and typed config
- COE-260: Domain model and orchestrator state machine
- COE-261: Local agent-server supervisor
- COE-262: REST client and conversation contract
- COE-263: Workspace manager and lifecycle hooks
- COE-264: Linear read adapter and issue normalization
- COE-265: WebSocket event stream, reconciliation, and recovery
- COE-266: Issue session runner
- COE-267: Linear MCP write surface
- COE-268: Orchestrator scheduler, retries, and reconciliation
- COE-269: Control-plane API and snapshot store
- COE-270: Repository harness and generated context artifacts
- COE-271: FrankenTUI operator client
- COE-272: Fake OpenHands server and protocol contract suite
- COE-273: Live local end-to-end suite
- COE-274: CLI packaging, doctor, and local operations docs
- COE-277: Implement hierarchy-aware task selection
- COE-278: Doctor live probe resolves repo-local OpenHands launcher paths reliably
- COE-280: Support workflow-owned OpenHands auth, provider, and launcher overrides at runtime
- COE-281: Support path-bearing OpenHands base URLs and MCP config at runtime
- COE-282: Support workflow-owned OpenHands conversation reuse policy at runtime
- COE-284: Add orchestrator run command to CLI and make it installable
- COE-286: Abort active CLI worker tasks on graceful orchestrator shutdown
- COE-287: Add opensymphony debug command for conversational session debugging
- COE-288: Add context condenser support to prevent LLM context window overflow
- COE-293: OpenHands agent has no filesystem tools - only FinishTool and ThinkTool
- COE-294: Detect LLM config changes and rehydrate conversations with updated env vars
- COE-382: Add supply-chain and security audits to CI
- COE-383: Decompose oversized session and TUI modules into focused submodules
- COE-384: Expand error-path tests for Linear client and workspace hooks
- COE-385: Resolve runtime tracking TODO in OpenHands session runner
- COE-386: Wire cargo-llvm-cov coverage reporting and regression floor into CI
- COE-387: Audit tracing spans and diagnostics for secret leakage
- COE-394: Frontend Workspace And Shared Schemas
- COE-395: Planning Artifact Schema And Session Service
- COE-397: Gateway API Client, Transport Adapters, And Reducers
- COE-398: Tauri Shell And Security Capabilities
- COE-399: Linear Read Coverage And Task Graph Cache
- COE-400: OpenHands Event Normalization And Runtime Mirror
- COE-401: Web App Entry And Deployment Modes
- COE-402: App Shell, Dashboard, Task Graph, And Run Views
- COE-403: Terminal And Log Renderer Prototype
- COE-404: Desktop Connection Profiles And Daemon Management
- COE-405: Linear Milestone, Issue, And Sub-Issue Mutations
- COE-406: Repository, Linear, And Research Analysis
- COE-407: Browser Transport And Remote Stream Protocols
- COE-408: Harness Adapter And Capability Model
- COE-409: Desktop Settings, Keychain, And Native Actions
- COE-410: Desktop Local Stream Optimization
- COE-411: Task Graph Editor And Runtime Overlay UI
- COE-412: Runtime Timeline And Terminal/Log Association
- COE-413: Implementation Plan Generator Stage
- COE-414: Diff, Validation, Approval, And Run Action Views
- COE-415: Milestone, Issue, And Sub-Issue Compiler
- COE-416: Dependency Graph And Plan Checks
- COE-417: Planning Workspace UI
- COE-419: Hosted Auth Placeholders And Web Parity
- COE-423: Model And Credential Settings
- COE-425: OpenHands Subscription Credential Adapter
- COE-426: Codex App-Server Prototype And Benchmarks
- COE-428: Model Configuration UI And Routing Metadata
- COE-429: Codex Approvals And Cross-Harness Routing
- COE-434: Long-running harness liveness and scheduler/runtime ownership contract
- COE-435: Long-running run observability fixtures and client-facing diagnostics
- COE-449: Desktop alpha recovery: replace stubs with functional app
- COE-452: DuckDB Prebuilt Developer Build Mode
- COE-453: Non-Interactive Init For Automation
- COE-454: OKF Bundle Schema And Legacy Capsule Mapping
- COE-456: OKF Writer, Lint, And Migration Fixtures
- COE-458: Catalog Reindex And Query Compatibility From OKF
- COE-460: OKF Export, Import, And Visibility Boundaries
- COE-461: Memory Graph DTOs And Gateway Endpoints
- COE-463: Docs Sync And MCP Admin Parity For OKF
- COE-464: Graph Extraction, Metrics, And Community Pipeline
- COE-465: Shared Graph Frontend Package And Reducers
- COE-467: Three.js Graph Renderer And Worker Layouts
- COE-468: Concept Inspector, Search, Filters, And Accessibility Fallback
- COE-469: Live Memory Graph Integration And Privacy Gates
- COE-471: Graph Scale, Visual Regression, And Web/Desktop Hardening
- COE-473: Desktop task graph dependency and run detail parity
- COE-475: ChatGPT OAuth For Codex Harness
- COE-476: Codex Production Harness Enablement
- COE-478: Harden model profile storage and validation follow-ups
- COE-479: Codex Debug Session Resume
- COE-480: Run Detail Metrics And Density
- COE-481: Model Configuration Codex Subscription Follow-Up
- COE-482: TUI Codex Token Usage Accounting
- COE-483: Codex Event Content Summaries
- COE-484: Desktop Live Snapshot And Run Detail Refresh
- COE-486: Harness Interrupt Contract And Run Diagnostics
- COE-487: Desktop Run Detail TUI Parity
- COE-488: Lazy Desktop Launcher Command
- COE-489: OpenHands Agent-Server Interrupt Adapter
- COE-490: Codex App-Server Turn Interrupt Adapter
- COE-491: Desktop Run Detail Action Wiring And Cleanup
- COE-492: Merging Supersedes Human Review Polling
- COE-493: Desktop Operations Integration Hardening
- COE-498: Tree-sitter Provider Skeleton And Rust Parsing
- COE-499: Memory Context AST Provider Integration
- COE-500: Query Packs For Supported Agent Languages
- COE-501: Code Intelligence Persistence And Ingestion
- COE-502: Read-Only AST MCP And CLI Tools
- COE-503: Code Intelligence Performance Docs And Hardening
- COE-504: Linear Polling And Rate-Limit Recovery
- COE-505: Add scheduler-side Codex stdio interrupt channel
- COE-506: Invert CodeIntelIndex trait ownership after AST memory integration
- COE-507: Deduplicate query-pack assets for grammar variants
- COE-508: Cache code-intel parsers and compiled query packs
- COE-520: Route desktop Knowledge Graph through native gateway commands
- COE-521: Workflow Target Branch Model And Init Customization
- COE-522: Init Target Branch Prompt And Flag
- COE-523: Update Workflow Settings Mode
- COE-524: Template Docs And Settings Hardening
- COE-525: Desktop Installer Contract And Release Metadata
- COE-526: Desktop Release Bundle Pipeline
- COE-527: Source Build Fallback And Prerequisites
- COE-528: App Download Install And Launch Flow
- COE-529: Desktop Auto-Update Flow
- COE-530: Installer Docs And End-To-End Validation
- COE-531: Workspace Shell Graph Hero And Surface State
- COE-532: Symbol Identity Container Chain And Code Read Model
- COE-533: Code Graph DTOs Gateway Routes And Native Commands
- COE-534: Code Graph Frontend Surface Adapters And Inspector
- COE-535: Run Diff Symbol Navigation And Code Overlay
- COE-536: Cross Graph Code Memory And Work Chips
- COE-537: Code Graph Scale Accessibility And Parity Hardening
- COE-540: Canonical Codex Thread Reuse And Workspace Retention
- COE-541: Durable Codex Thread Archive And Debug Recovery
- COE-542: Target Branch Code Index And Revision Snapshots
- COE-543: Workspace Code Overlay And Composite Graph
- COE-544: Indexed Agent Code Context And Retrieval
- COE-545: Edge Delta And Module Topology Diff
- COE-546: Code Graph Bootstrap UX And End-To-End Validation
- COE-547: Central Multi-Repository Config And Safe Migration
- COE-548: Canonical Repository Binding And Task Propagation
- COE-549: Verified Checkouts Instructions And Harness Envelopes
- COE-550: Per-Instance Memory Catalog And Source Migration
- COE-551: Scoped Cross-Repository Memory And Leaf Overlays
- COE-553: Parent Execution Roots And Child Workspace Reuse
- COE-554: Restart-Safe Parent Integration Controller
- COE-555: Parent Repair Review And Merge Lifecycle
- COE-556: Bottom-Up Subtree Cleanup And Recovery
- COE-562: Implement artifact validation and digest primitives
- COE-563: Implement task-packet admission and freeze tooling
- COE-564: Implement verifier execution and outcome records
- COE-565: Implement isolated workspace materialization
- COE-566: Implement configurable run matrices and scheduling
- COE-567: Implement run lifecycle and process-protocol primitives
- COE-608: ACP Profiles And Executable Protocol Client
- COE-609: ACP Session Ownership And Durable Recovery
- COE-610: ACP Client Callbacks And Session Configuration
- COE-611: ACP Execution Routing And Worker Integration
- COE-612: ACP Operator Requests And Response Routing
- COE-613: ACP Extensions And Harness Operations
- COE-615: ACP Runtime Conformance And Live Qualification
## Source refs
- COE-252
- COE-253
- COE-254
- COE-255
- COE-256
- COE-258
- COE-259
- COE-260
- COE-261
- COE-262
- COE-263
- COE-264
- COE-265
- COE-266
- COE-267
- COE-268
- COE-269
- COE-270
- COE-271
- COE-272
- COE-273
- COE-274
- COE-277
- COE-278
- COE-280
- COE-281
- COE-282
- COE-284
- COE-286
- COE-287
- COE-288
- COE-293
- COE-294
- COE-382
- COE-383
- COE-384
- COE-385
- COE-386
- COE-387
- COE-394
- COE-395
- COE-397
- COE-398
- COE-399
- COE-400
- COE-401
- COE-402
- COE-403
- COE-404
- COE-405
- COE-406
- COE-407
- COE-408
- COE-409
- COE-410
- COE-411
- COE-412
- COE-413
- COE-414
- COE-415
- COE-416
- COE-417
- COE-419
- COE-423
- COE-425
- COE-426
- COE-428
- COE-429
- COE-434
- COE-435
- COE-449
- COE-452
- COE-453
- COE-454
- COE-456
- COE-458
- COE-460
- COE-461
- COE-463
- COE-464
- COE-465
- COE-467
- COE-468
- COE-469
- COE-471
- COE-473
- COE-475
- COE-476
- COE-478
- COE-479
- COE-480
- COE-481
- COE-482
- COE-483
- COE-484
- COE-486
- COE-487
- COE-488
- COE-489
- COE-490
- COE-491
- COE-492
- COE-493
- COE-498
- COE-499
- COE-500
- COE-501
- COE-502
- COE-503
- COE-504
- COE-505
- COE-506
- COE-507
- COE-508
- COE-520
- COE-521
- COE-522
- COE-523
- COE-524
- COE-525
- COE-526
- COE-527
- COE-528
- COE-529
- COE-530
- COE-531
- COE-532
- COE-533
- COE-534
- COE-535
- COE-536
- COE-537
- COE-540
- COE-541
- COE-542
- COE-543
- COE-544
- COE-545
- COE-546
- COE-547
- COE-548
- COE-549
- COE-550
- COE-551
- COE-553
- COE-554
- COE-555
- COE-556
- COE-562
- COE-563
- COE-564
- COE-565
- COE-566
- COE-567
- COE-608
- COE-609
- COE-610
- COE-611
- COE-612
- COE-613
- COE-615