# Operations
For first-time multi-repository setup, use the
[multi-repository guide](multi-repository.md). For a local ACP agent, use the
[ACP harness guide](acp.md). This page covers the detailed commands and
failure handling after the route is configured.
This document covers the current local operator workflow for OpenSymphony.
Run detail and TUI projections expose sanitized repository, target commit,
instruction hash, lease, repair, verification, and cleanup facts when those
facts are authoritative. Blocked and cleaning states remain distinct from
completed, and remote views do not expose unrestricted local paths.
Packaging note: crates.io publishes one package, `opensymphony`. The internal
`crates/opensymphony-*` directories are module trees inside that package, not
separately published dependencies.
## 1. Core commands
Recommended CLI commands:
- `opensymphony init`
- `opensymphony update`
- `opensymphony run`
- `opensymphony app` or `opensymphony desktop`
- `opensymphony debug <issue-id>`
- `opensymphony tui`
- `opensymphony doctor`
- `opensymphony rehydrate <issue-id> --reason "..."`
During restart recovery, `opensymphony run` loads the scheduler-owned
hierarchy and lease artifact before reconciling terminal workspaces. The
artifact is an internal durable record; operators should not edit it manually.
Recovery rebuilds ancestor retention before cleanup, and cleanup remains
blocked while any owner-identified lease for the checkout generation is active.
For a captured terminal parent, recovery also resumes its durable subtree
cleanup intent. The persisted order is parent worktree detachment, release of
that parent's lease owners, deepest-first descendant deletion, and parent-root
deletion. A higher-ancestor lease or an unexpired diagnostic hold keeps the
affected generation pending. Cleanup errors remain in the controller and are
retried on later ticks; operators should correct the reported hook, Git, or
filesystem condition rather than delete the path manually. A surviving
terminal descendant already named by an incomplete subtree-cleanup intent stays
under that intent during bootstrap; recovery does not reacquire a leaf lease or
route it through generic terminal cleanup.
Claimed, running, and retry-queued executions fence their exact workspace
generation. An unavailable OpenHands conversation store or a failed durable
lease/completion receipt also leaves cleanup pending for the next tick.
Cleanup refreshes the full tracker snapshot before retrying deletion, so a
newly reopened descendant is fenced before its workspace generation is
resolved. Missing generation-bound conversation evidence also blocks removal
unless a preparation-failed run proves that no conversation binding existed.
## 2. First-run flow
```bash
cargo install opensymphony
opensymphony install openhands
opensymphony --help
cd /path/to/target-repo
opensymphony init
opensymphony update
opensymphony run
```
If you already run an external OpenHands agent-server, you can skip
`opensymphony install openhands`.
The desktop launcher is intentionally lazy. `opensymphony app` and its visible
alias `opensymphony desktop` verify and launch a cached desktop bundle from
`~/.opensymphony/desktop/<version>/` without making the normal Cargo install
compile Tauri, npm, or platform desktop dependencies. On a cache miss, it reads
`opensymphony-desktop-release-index.json` from the versioned GitHub release for
the running CLI, downloads the compatible archive, verifies the archive and
installed manifest, then promotes the bundle into the versioned cache. Existing
cached bundles check the latest release index for newer compatible updates
before launch. Set `OPENSYMPHONY_DESKTOP_RELEASE_INDEX_URL` to test a fake
release server or use a private mirror. For early local testing, pass
`--bundle-dir <path>` or set
`OPENSYMPHONY_DESKTOP_BUNDLE_DIR` to a bundle directory containing
`opensymphony-desktop-manifest.json`. The manifest records the OpenSymphony
version, platform, architecture, relative executable path, and executable
SHA-256. Local bundle materialization copies regular files and directories;
symlinked bundle entries should be packaged by the downloaded archive path
instead of this local smoke path.
When no compatible prebuilt asset is available or a release download fails, a
normal run attempts the source-build fallback after checking Rust/Cargo,
Node/npm, source archive extraction, and platform desktop/Tauri prerequisites.
Interactive update prompts use `Update before launch? [Y/n]`; pressing Enter
accepts the update, and non-interactive runs update by default unless
`--no-update` is supplied.
Maintainers can build the current release bundle assets from a checkout:
```bash
npm run build --workspace=@opensymphony/desktop
npm run package:release --workspace=@opensymphony/desktop
```
The package command writes
`dist/desktop-release/opensymphony-desktop-v<VERSION>-<PLATFORM>-<ARCH>.tar.gz`
and `dist/desktop-release/opensymphony-desktop-release-index.json`. Upload the
archive first and the release index last. The index is the CLI-consumable
metadata file; it should never be published before the referenced archive is
available. If an index already exists in the output directory, the package
command preserves entries for other platform/architecture assets and replaces
only the current asset entry while keeping unknown top-level metadata. It also
fails before writing metadata when the desktop package, Tauri crate, or Tauri
config version does not match the release version, or when Cargo lockfile drift
would change the desktop dependency graph.
Use `--install-path <dir>` or `OPENSYMPHONY_DESKTOP_INSTALL_PATH` to choose a
custom install root. That root contains versioned bundles such as
`<dir>/<version>/`; it is not the bundle directory itself. `--dry-run` remains
read-only and never starts source-build prerequisite installation. Download
metadata, auto-update prompting, fallback order, and path-safety rules are defined in
[Desktop App Installer And Auto-Update Spec](specs/desktop-app-installer-auto-update-spec.md).
Important `init` behavior:
- fetches the current template payload
- leaves an existing `AGENTS.md` untouched and writes starter guidance to
`AGENTS-example.md` during first-time setup
- prompts before overwriting repo-owned files
- optionally scaffolds AI PR review assets
- can configure GitHub Actions variables, the `review-this` label, and the
optional AI review secret automatically when `gh` is installed and can access
the target repository
- prompts whether to commit and push the generated OpenSymphony files; when
accepted, it stages only files it wrote, commits `chore: bootstrap
OpenSymphony`, and pushes `HEAD` to the detected remote
- supports `--non-interactive` for automation; pass explicit flags for prompt
decisions and unresolved existing-file conflicts fail before any files are
written
- copies `.agents/skills/` recursively so helper scripts, query files, and
reference docs all arrive together
- keeps bootstrap guidance in CLI output and the central OpenSymphony docs
instead of copying `docs/` files into the target repository
Automation-friendly target repo provisioning can run without stdin prompts:
```bash
cargo install opensymphony
opensymphony install openhands
cd /path/to/target-repo
opensymphony init \
--non-interactive \
--linear-project-slug my-linear-project \
--conflict-policy overwrite \
--commit-and-push
```
For scripts that scaffold AI PR review too, add the review flags explicitly:
```bash
opensymphony init \
--non-interactive \
--ai-pr-review \
--configure-github \
--ai-review-provider-kind openai-compatible \
--ai-review-model-id accounts/fireworks/models/glm-5p1 \
--ai-review-base-url https://api.fireworks.ai/inference/v1 \
--ai-review-require-evidence true \
--ai-review-secret-env LLM_API_KEY \
--linear-project-slug my-linear-project \
--conflict-policy overwrite
```
If `--configure-github` is omitted, init still writes the AI PR review files
when `--ai-pr-review` is present, but it prints the manual `gh` commands instead
of mutating repository variables, secrets, or labels. If a non-interactive run
finds an existing generated file and `--conflict-policy` was not supplied, it
fails before applying the template.
When `--ai-review-secret-env` is used, the named environment variable must be
present and non-empty; init fails rather than setting a blank GitHub secret.
For already-initialized repositories, `opensymphony update` is the fast
maintenance path:
- checks the latest published `opensymphony` version and skips
`cargo install opensymphony --locked` when the running CLI is already current
- refreshes changed or new template-managed files under `.agents/skills/`
- leaves `WORKFLOW.md`, `AGENTS.md`, `.github/*`, and repo-local extra skills
alone
OpenSymphony 2.11.0 raises the minimum supported Rust version to 1.97.1. An
older CLI may invoke Cargo through a checkout-local toolchain override, so use
this one-time upgrade path when moving from a release before 2.11:
```bash
rustup update stable
cargo +stable install opensymphony --locked
```
Use workflow settings mode when only the managed branch or review-provider
markers need to change:
```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
```
Settings mode updates managed `WORKFLOW.md` markers, rewrites known legacy
branch-control phrases when the target branch changes, and skips the CLI
reinstall, template skill refresh, and memory bootstrap. `--code-review
openhands` records the marker and attempts to enable an existing
`.github/workflows/ai-pr-review.yml` through `gh workflow` but does not install
or repair a missing workflow file; `codex` and `none` record the marker and
attempt to disable an existing OpenHands review workflow. If `gh` is
unavailable, unauthorized, or cannot access Actions, verify or adjust the
workflow state manually.
Normal user installs use bundled DuckDB. This keeps `cargo install
opensymphony` and `opensymphony update` turnkey even when the memory database is
enabled.
Power users who want to avoid compiling bundled DuckDB may install a system
DuckDB development package and build without default features. On the
macOS/Homebrew development host, install and pin DuckDB once:
```bash
brew install duckdb
brew pin duckdb
```
Homebrew currently provides `duckdb`, not a versioned `duckdb@...` formula.
Pinning keeps the verified local version from moving during routine Homebrew
upgrades. The expected version for this release line is DuckDB `1.5.3`. To
build manually against that system library:
```bash
export DUCKDB_LIB_DIR="$(brew --prefix duckdb)/lib"
export DUCKDB_INCLUDE_DIR="$(brew --prefix duckdb)/include"
export DYLD_LIBRARY_PATH="$DUCKDB_LIB_DIR${DYLD_LIBRARY_PATH:+:$DYLD_LIBRARY_PATH}"
cargo install opensymphony --no-default-features --features duckdb-prebuilt
```
On Linux, set `DUCKDB_LIB_DIR`, `DUCKDB_INCLUDE_DIR`, and `LD_LIBRARY_PATH` to
the matching DuckDB installation. On Windows, set `DUCKDB_LIB_DIR`,
`DUCKDB_INCLUDE_DIR`, and add the DuckDB DLL directory to `PATH` before running
the same Cargo install command. This is a manual optimization path: verify a
memory command after installation, and expect to keep the runtime library
available anywhere the installed binary runs.
To update a power-user system-linked install, run the same Cargo install command
with the same environment first. Then run `opensymphony update` from a target
repository only to refresh template-managed agent assets. Starting with
`opensymphony update` may reinstall the default bundled build when a newer
release exists.
## 3. Recommended validation commands
For fast iterative development inside this repository on the macOS/Homebrew
host, use the system-linked developer aliases:
```bash
cargo fmt --check
cargo check-system-duckdb
cargo test-system-duckdb
cargo test-system-duckdb --test memory
cargo clippy-system-duckdb
```
If system DuckDB is unavailable, use the portable downloaded fallback aliases:
```bash
cargo check-dev
cargo test-dev
cargo clippy-dev
```
The system aliases set `DUCKDB_LIB_DIR`, `DUCKDB_INCLUDE_DIR`, and
`DYLD_LIBRARY_PATH` for the aliased command. The fallback aliases set
`DUCKDB_DOWNLOAD_LIB=1` only for the aliased command. Both alias families use
`--no-default-features --features duckdb-prebuilt`. If a downloaded fallback
command must override `CARGO_TARGET_DIR`, use an absolute path. Release-
sensitive, packaging, and dependency work should still include the default
bundled-mode checks so `cargo install opensymphony` remains turnkey for users:
```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo test --test init
cargo test --test help
cargo test --test update
./scripts/smoke_local.sh
```
Dependency audit notes:
- COE-429 adds `jsonschema = 0.46.5` as the runtime validator for installed
Codex app-server JSON Schema payload checks. Release provenance was checked
against the `Cargo.lock` crates.io source/checksum entries for `jsonschema`
and its called-out transitive crates (`fancy-regex`, `fluent-uri`, and
`fraction`), the dependency tree was reviewed with `cargo tree -p jsonschema
--depth 2`, and `cargo audit` exited successfully against the current lockfile
on 2026-06-21. Re-run those checks when upgrading `jsonschema`.
Useful runtime checks:
```bash
curl http://127.0.0.1:2468/healthz
curl http://127.0.0.1:2468/api/v1/snapshot
curl http://127.0.0.1:2468/api/v1/capabilities
curl http://127.0.0.1:2468/api/v1/dashboard/snapshot
opensymphony tui --url http://127.0.0.1:2468/ --exit-after-ms 1200
```
## 4. Doctor expectations
`opensymphony doctor` is a real preflight tool.
It is optional troubleshooting/preflight help, not the primary install path for
managed local OpenHands. The normal setup flow is `cargo install opensymphony`
followed by `opensymphony install openhands`.
Current scope:
- loads and resolves the target repo `WORKFLOW.md`
- renders the workflow prompt with a synthetic issue
- validates required local tools
- validates bundled OpenHands tooling
- probes the configured OpenHands transport
- can create a temp conversation and verify runtime readiness
Expected checks include:
- config parses
- target repo exists
- `WORKFLOW.md` resolves cleanly
- required env-backed config values exist
- `cargo`, `curl`, `git`, and `uv` are on `PATH`
- the pinned OpenHands toolchain is present
- loopback/local safety warnings are surfaced
When the configured transport uses managed local OpenHands, `doctor` can
bootstrap the pinned tooling into the configured `openhands.tool_dir` before
continuing the rest of its checks.
## 4.0 Code Graph repository indexing
Trigger a target-branch repository snapshot through the gateway or desktop
native mirror:
```bash
curl -X POST http://127.0.0.1:2468/api/v1/code/repos/opensymphony/index
```
The server reads the branch marker in `WORKFLOW.md` (default `develop`) and
resolves the commit from `origin/<branch>` or the local branch. It reads Git
objects without running repository code, applies the configured Tree-sitter
limits, and writes immutable revision membership in bounded batches. Repeated
indexing of a later commit reuses unchanged paths and records deletions without
removing older revisions. Requests return an accepted report; inspect the event
journal for progress and the terminal completion/failure event. Concurrent
requests are serialized by the index writer.
The operator-facing equivalent is the Code Graph empty state: select the
configured repository and choose `Index repository`. It is safe to start from
an empty `.opensymphony/memory/memory.duckdb`; the repository row is exposed
with zero counts until the job begins. `accepted` and `progress` reports show
coverage, `failed` and `unavailable` reports show diagnostics with a retry
action, and `code_graph_updated` causes the shell to refresh the baseline. If
the event stream is silent during an accepted/progress job, the shell polls the
repository summary and refreshes as soon as an indexed baseline is visible.
The provenance strip should show the configured target revision and whether a
view is baseline, workspace-composed, stale, truncated, or partially analyzed.
For a production transport smoke, use the gateway endpoint rather than the
fixture workbench:
```bash
curl http://127.0.0.1:2468/api/v1/code/repos
curl -X POST http://127.0.0.1:2468/api/v1/code/repos/<repo-id>/index
curl 'http://127.0.0.1:2468/api/v1/code/repos/<repo-id>/graph?mode=atlas'
```
## 4.1 Subscription Credential Operations
OpenAI ChatGPT/Codex subscription mode is explicit and feature-gated. Build or
install OpenSymphony with `--features openhands-subscription-credentials`, then
configure the target repo workflow with
`openhands.conversation.agent.llm.credential_mode: openai_subscription`.
Credential establishment belongs to the documented OpenHands SDK flow or to a
future hosted credential broker. For local or self-hosted use, run the
OpenHands SDK browser or device-code login in the environment that owns the
credential store, keep refresh material in the selected auth directory, and
export only the short-lived access-token reference expected by the workflow
before starting `opensymphony run`. Do not place OAuth JSON files, access
tokens, or refresh tokens inside issue workspaces or repository files.
`auth_directory_env`, `auth_method`, `open_browser`, and `force_login` are
operator/bootstrap metadata for that credential setup step; they are preserved
for status and diagnostics, while the runtime conversation request resolves only
the short-lived access token and optional account identity header.
Validation for subscription mode should include:
- mocked subscription request construction tests
- redaction checks for manifests, diagnostics, and debug output
- live integration only when a valid subscription credential and pinned SDK
support are available
Codex app-server subscription readiness is separate from the OpenHands SDK auth
directory. The gateway reports local Codex readiness through model settings by
running supported Codex CLI checks only:
```bash
codex --version
codex app-server --help
codex login status
```
When `codex login status` is logged out or expired, run
`codex login --device-auth`. Some ChatGPT accounts require enabling
**Security and login -> Enable device code authorization for Codex** before the
device-code flow succeeds. To revoke local Codex access, run `codex logout` and
use ChatGPT account settings for account-side revocation. OpenSymphony must not
read private Codex credential files or copy access/refresh material into
workspaces, logs, workflow files, Linear comments, or browser payloads. Gateway
readiness checks are cached briefly and have bounded per-command timeouts so
operator UI polling cannot hang on a stalled local Codex command.
The local Codex app-server harness path launches
`codex --dangerously-bypass-hook-trust app-server --stdio` and is advertised as
available when clients read `/api/v1/capabilities`. Before starting a run,
OpenSymphony generates the JSON Schema from the installed Codex CLI and
validates its full-automation `thread/start`, `thread/resume`, rollback
`thread/list`, `thread/archive`, `thread/unarchive`, and `turn/start` payloads. A new issue starts a thread; a
workspace with its canonical manifest resumes it. If the first manifest write
fails after a start, OpenSymphony archives that newly created thread and does
not start a turn. If the installed schema rejects any lifecycle payload, update
Codex before running the Codex harness. Unsupported or logged-out Codex
installations must fail with the readiness guidance above instead of partially
starting an issue. Loopback WebSocket and hosted Codex worker pools remain
non-production paths.
For cross-harness route testing, run `opensymphony run --dry-run`.
OpenSymphony will still poll Linear and prepare workspaces, but the worker
returns a route preview instead of launching a model-backed harness. The preview
is recorded as a `routing.decision` runtime event and includes the selected
harness, model, and model profile. To force a local process override without
editing workflow config, start the daemon with `OPENSYMPHONY_HARNESS`, and pass
`OPENSYMPHONY_MODEL` / `OPENSYMPHONY_MODEL_PROFILE` when a launcher wants to use
the active model profile selected in the desktop or web UI.
The Codex local stdio route executes the configured Codex binary with
`cwd == issue_workspace_path`. `OPENSYMPHONY_CODEX_BIN` is a trusted local
operator override and must not be treated as a hosted or multi-tenant input.
Approval requests are surfaced through normalized runtime events and shared
approval-center data models, but approval decisions are not yet forwarded from
the operator action plane into a live Codex stdio session in this alpha route.
The alpha model configuration panel exposed by the web and desktop shells uses
the shared model profile state store, but those entrypoints currently construct
it without durable storage. Treat profile edits as session-local until a
desktop secure-settings backend or hosted settings service is wired in. The UI
may keep model strings, routing hints, subscription bootstrap metadata, and
stored credential references in memory, but raw provider keys and OAuth refresh
material must stay in the selected keychain, OpenHands auth directory, or
hosted secret store.
## 5. Linear operational model
OpenSymphony 1.0.0 is GraphQL-only for agent-side Linear operations.
Operational implications:
- there is no separate local Linear bridge process to start
- initialized target repos rely on `LINEAR_API_KEY`
- operators may set `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET` instead of
relying on a long-lived `LINEAR_API_KEY`; `opensymphony run` mints a Linear
OAuth client-credentials token at startup and uses it for scheduler and
worker Linear calls
- `opensymphony run` keeps its local worker/snapshot tick every 5s, while
Linear reads use cheaper internal cadences: running state every 30s,
dispatch discovery every 60s, terminal cleanup every 5 minutes, and full
issue details hourly after startup/dispatch. When all required children of a
waiting parent have terminal orchestrator outcomes, full details refresh on
the 5-minute terminal cadence so parent eligibility can use a complete
hierarchy observation
- if Linear returns a long rate-limit reset, the scheduler pauses all Linear
reads behind one shared cooldown but continues processing worker updates; the
same cooldown also suppresses later parent-provider eligibility lookups in
the current dispatch pass without discarding prepared leaf launches. The
Linear client only sleeps inline for short rate-limit retry windows up to the
lower of `tracker.retry_policy.max_backoff` and 30 seconds
- the checked-in helper lives at
`.agents/skills/linear/scripts/linear_graphql.py`
- checked-in query files under `.agents/skills/linear/queries/` are the
supported mutation/query surface
- issue creation, issue rewrite passes, blocker relations, comments, PR
attachments, and project updates should all use those checked-in assets
Smoke test:
```bash
cd /path/to/target-repo
python3 .agents/skills/linear/scripts/linear_graphql.py \
--query-file .agents/skills/linear/queries/viewer.graphql
```
## 6. Project memory
Project memory stores policy and learned structure in
`.opensymphony/memory/memory.yaml` and private runtime artifacts under
`.opensymphony/memory/`. `opensymphony run` captures terminal issue transitions
automatically when `memory.auto_capture` is enabled in `config.yaml`:
```yaml
memory:
auto_capture: true
auto_archive: false
```
With a central instance config, automatic capture uses the configured catalog
even when the selected checkout has no repository-local memory YAML. After a
capsule write, the reload falls back to the normal default policy lookup rather
than treating the absent local file as an explicit required path.
Manual commands remain available for setup, backfill, inspection, and guarded
archive operations:
```bash
opensymphony memory init
opensymphony memory capture COE-123
opensymphony memory status
opensymphony memory brief COE-123
opensymphony memory related --paths crates/opensymphony-openhands
opensymphony memory sync-docs --since-last-sync
opensymphony memory lint --public-docs
opensymphony memory lint --okf
opensymphony memory reindex --from-okf
opensymphony memory export-okf --visibility public --output public-okf
opensymphony memory import-okf public-okf
```
Add `--dry-run` to write commands when an operator wants a non-writing preview.
Use `opensymphony memory import --source-file completed.yaml` only for
deterministic imports, migrations, tests, or external exports. Failed Linear or
GitHub access should be fixed before live capture is retried.
`memory capture` creates or refreshes issue capsules, updates
`.opensymphony/memory/memory.duckdb`, and refreshes markdown indexes when
enabled. Normal builds use DuckDB's bundled native library so operators do not
need to install DuckDB separately, at the cost of heavier Rust compile time and
a larger binary. Repository development can opt into the `duckdb-prebuilt`
feature through the system-linked `cargo check-system-duckdb`,
`cargo test-system-duckdb`, and `cargo clippy-system-duckdb` aliases, or the
downloaded fallback `cargo check-dev`, `cargo test-dev`, and `cargo clippy-dev`
aliases. Treat that native dependency as part of the hosted deployment threat
model before enabling memory in a multi-tenant service.
Memory capture does not archive Linear issues.
When automatic capture completes a terminal parent capsule, `opensymphony run`
persists a capture acknowledgement before allowing subtree cleanup. A failed
capture is not acknowledged, so the parent evidence and protecting leases stay
available for the next capture attempt. If acknowledgement-state persistence
fails, the scheduler rolls back the in-memory cleanup intent so the next
automatic capture retries before any evidence is removed. Cleanup also remains
fenced while a parent repair provider intent lacks its terminal receipt.
After acknowledged parent cleanup removes the runtime root, the completed
cleanup intent remains the restart-safe automatic-capture marker. A malformed
conversation manifest on any generation-bound cleanup target blocks removal
until its archival evidence is repaired.
Read commands such as `memory status`, `memory brief`, `memory related`, and
`memory context` open the DuckDB index in read-only mode and do not run schema
migrations. Capture, import, OKF import/export, docs sync, reindex, archive,
automatic terminal capture, and code-intelligence persistence acquire the
instance coordination lock before writing. The local MCP server holds that
same lock for its lifetime, so migration and direct writers cannot copy or
index a torn catalog. Prefer the CLI or MCP admin surface for maintenance;
direct file or DuckDB access is an offline recovery and diagnostics fallback
only.
Each `opensymphony run` claims the configured state and workspace roots before
constructing tracker, memory, or workspace services. A second live process
using either root fails without polling Linear or creating a workspace. The
ownership marker records the process ID and, when available, a process-start
incarnation; stale markers are atomically quarantined before the root is
reclaimed, and a reused PID does not keep an old marker live when its
incarnation differs. The marker is released when the run shuts down, including
legacy single-repository runs.
When a worker outcome schedules a retry, the run manifest records the retry's
scheduled time, due deadline, reason, and redacted error summary. Restart
recovery restores those values and waits for the original deadline. Failed
stall-stop requests remain attached to the running execution until a later
stop attempt is acknowledged, so a remote worker cannot be forgotten after a
transient interrupt failure.
An interrupted `Preparing` or `Prepared` run with no conversation manifest is
recovered as a retry using its persisted retry count; once the configured
retry limit is reached it is parked as exhausted instead of being dispatched
as a fresh attempt.
For worker or tool access, `opensymphony run` starts the read-only memory server
when memory is initialized and `memory.serve` is not disabled. The supervised
server binds to loopback on an ephemeral port by default, reports the endpoint
through the control-plane recent events, and passes
`OPENSYMPHONY_MEMORY_ENDPOINT` into managed local OpenHands workers. Manual
operation is also available with `opensymphony memory serve --addr
127.0.0.1:8765`, which exposes MCP-style `initialize`, `tools/list`, and
`tools/call` JSON-RPC methods at `/mcp`. Set `OPENSYMPHONY_MEMORY_TOKEN` or
pass `--token` to require bearer-token access for read tools. Admin tools
(`memory.capture`, `memory.sync_docs`, `memory.lint`, `memory.reindex`,
`memory.export_okf`, `memory.import_okf`, and `memory.ingest_code_intel`)
require `OPENSYMPHONY_MEMORY_ADMIN_TOKEN` or `--admin-token`. When only the
admin token is configured, it also gates read tools; do not inject that token
into ordinary worker or shared managed-server environments. A configured
read token is likewise injected only as the per-conversation worker grant, not
into the shared managed-server environment. Authenticated operator calls using
the configured read or admin bearer may still perform ordinary read calls on a
supervised server; only unauthenticated unscoped reads are rejected as worker
requests. When `code_intel.enabled` is true,
`tools/list` exposes the read-only `code.graph.context` indexed discovery tool;
when `code_intel.ast.enabled` is true, it also exposes `code.ast.*` inspection
tools. The graph tool is bounded and can use the
server-resolved run workspace overlay; it never accepts a client filesystem
root or source-snippet override. The ad hoc
`code.ast.query` tool is available for local trusted use without tokens, and is
admin-gated when an admin token is configured. AST work runs off the async
server thread, enforces configured file/match/capture limits, rejects paths and
symlinks outside the repo root, skips generated/vendor/build/cache directories
during traversal and oversized files with trace warnings, and never executes
target-repo code. Direct file requests inside skipped directory names still pass
through containment and resource checks. See
[`docs/code-intelligence.md`](code-intelligence.md) for agent and operator
usage.
Linear archival is a separate command and is guarded by captured memory:
```bash
opensymphony linear archive --issues COE-123
```
For explicit issue selectors, the archive command captures live Linear and
GitHub evidence before evaluating the guard. It blocks issues that have no
capsule or unresolved capture warnings unless `--force` is supplied. Normal mode
resolves Linear credentials from `WORKFLOW.md` and calls the Linear GraphQL
archive mutation.
If the repo uses managed local OpenHands, archive also moves the issue's
persisted OpenHands conversation into the repo-scoped `archived/` store. Archive
uses the workspace `.opensymphony/conversation.json` manifest when present and
falls back to scanning managed conversation `meta.json` files for a matching
`workspace.working_dir` issue key, so legacy flat conversations and repo-scoped
`active/` conversations can still be moved even when workspace metadata is
stale. Normal orchestrator runs use the sibling `active/` store, while
`opensymphony debug COE-123` searches active and archived stores and starts the
managed server against the store containing the requested conversation. If
another OpenHands server is already bound to the configured port with a
different store, stop it and retry the debug command.
For issues last run through the local Codex app-server harness,
`opensymphony debug COE-123` reads the recorded Codex thread id, unarchives it
when terminal reconciliation archived it, and then runs `codex resume
<thread-id>` from that exact issue workspace. Set `OPENSYMPHONY_CODEX_BIN` to
override the Codex binary. Use `opensymphony debug COE-123 --app` to unarchive
and print `codex://threads/<thread-id>` without launching interactive Codex.
See [Project Memory](memory.md) for the full command surface, import YAML
schema, and troubleshooting notes.
## 7. Rehydration
Rehydration is the explicit recreation of an OpenHands conversation while
preserving enough history for continuation.
Use it for:
- API key rotation
- broken persisted conversation state
- intentional provider/model changes
Examples:
```bash
opensymphony rehydrate COE-123 --config ~/.opensymphony/config.yaml --reason "API key rotation"
opensymphony doctor --config ./config.yaml --rehydrate
```
## 8. Local safety
- prefer loopback-only OpenHands targets for local development
- treat target repos and prompts as trusted local input
- do not keep unrelated OpenHands servers running on the same configured port
- stop `opensymphony run` with Ctrl-C so the orchestrator can terminate its
managed OpenHands process tree; Ctrl-Z only suspends the orchestrator and can
leave the server bound to the configured port
- do not store provider secrets in checked-in files
## 9. Migration note
Central configuration migration is an explicit operator action. Use
`opensymphony migrate preflight --repo <path>` to inspect legacy
`config.yaml`/`WORKFLOW.md` without changing files, then use `migrate apply`
with the same paths to create a staged central config. The generated config
uses `legacy_single`, so migration does not activate strict multi-repository
routing. It records a config generation and an activation marker, preserves
the workflow body as repository implementation guidance, and keeps a backup
under `.opensymphony/migration/backups/`. Reports contain only paths, hashes,
field names, and boolean risk indicators; literal secret values and
credential-bearing remote values are never printed or serialized.
If apply is interrupted after staging or replacement, run
`opensymphony migrate rollback --config <central-config>` once the strict-run
marker is absent. Rollback restores the backed-up runnable generation and
leaves the backup evidence in place. Migration rejects repository-creation
hooks, query/fragment-bearing remotes, literal credentials embedded in hook
commands, and ambiguous credential expressions before activation; hook
credentials must use environment indirection. Existing repository-local
memory entries are copied into
the central catalog; identical repeat applies are idempotent, while divergent
entries fail as a recoverable conflict instead of silently keeping stale data.
The memory server marks its catalog as active while running, so read-only
preflight can inspect a live legacy writer without copying or writing anything.
Apply and
the server claim the same atomic `.opensymphony/memory.migration.lock` before
reading or copying the catalog; the server holds it for its lifetime. The lock
and activity marker record an owner PID and process incarnation, so stale
ownership from an unclean exit can be reclaimed while a live owner still
blocks migration/startup.
Stale lock recovery atomically renames the old lock to a unique quarantine file
before removing it; it never removes a newly-created owner lock at the shared
path. Project-set central configs are supported by doctor modes; probes use the
selected repository policy and do not inspect an unrelated launch-directory
checkout. Strict attach still requires a compatible verified checkout and
runtime envelope.
After front matter is moved, `doctor`, `debug`, and `rehydrate` load the central
policy so operational recovery continues to use the migrated OpenHands and
tracker settings.
For `legacy_single`, the same central policy resolves the selected repository's
`instructions.path` beneath its checkout instead of silently reverting to the
checkout root `WORKFLOW.md`.
Strict repository-bound runs publish checkout generations under the configured
workspace root. Operators should treat a generation manifest as immutable
provenance: it records the canonical remote fingerprint, target branch and
commit, instruction hash/source commit, and verification state. Drift or
partial publication is quarantined and retried as a new generation; do not
manually reset a quarantined checkout into service. The runtime envelope also
records that current local containment is process `cwd` containment on a
trusted host, not a sandbox boundary.
Parent runs publish a separate generation-scoped root below
`workspace.root/parents/`. Inspect `parent-manifest.json`,
`child-checkouts.json`, and `.opensymphony/parent-runtime.json` together when a
parent cannot launch. The workspace manager also keeps the authoritative copy
of each generation's checkout map below
`workspace.root/.opensymphony-parent-pins/`; a mismatch means the runtime copy
was modified and must not be repaired in place. Preparation blocks before a repository operation when a
required child subtree lacks an active ancestor lease, a retained generation is
stale or dirty, merge evidence is ambiguous across repositories, a remote no
longer matches policy, or a contained worktree fails its shared-storage and
path checks. Parent preparation also rejects retained-checkout local/worktree
HTTP, credential, transport, SSH-command, protocol, and URL-rewrite settings
before an authenticated fetch; remove or reconcile those settings before
retrying. Checkout-controlled process filters are rejected before integration
worktree creation, while retained hooks and host-level Git configuration are
disabled for that operation. Do not repair generated parent files or substitute
a filesystem path for the recorded opaque handle; reconcile the hierarchy/lease
evidence or retained checkout and rematerialize the generation. A configured
`after_create` hook is required for parent roots too; its failure rolls back the
incomplete root, a hook-created root-level Git repository also fails and rolls
back, and reuse requires the hook completion receipt. Parent paths include a
stable issue-identity digest after the sanitized identifier.
For a blocked parent repair, inspect the repair attempt's provider-operation
ledger before intervening. A pending operation is an intent whose provider
result must be reconciled first; do not create another branch or PR manually.
`provider_unavailable`, `failed_checks`, `review_rejected`,
`externally_closed`, `force_pushed`, and `merge_conflict` preserve the attempt
for retry or operator repair. Requested changes return the same attempt to its
recorded branch and PR. A stage-specific failure is stored as a bounded,
redacted repair diagnostic and retried without stopping the rest of the
scheduler tick. For a Codex review profile, the PR-open scan is the
initial request and later requested-change heads use an exact `@codex review`
comment; only completion and findings associated with the current pushed head
affect automated-review eligibility. Crash recovery accepts a trigger comment
only from the identity behind the configured review credential. Review findings
come from unresolved provider threads. Every unresolved non-Codex human thread,
including a `COMMENTED` review or a thread retained from an earlier head, blocks
merge until it is resolved; its bounded body and location are persisted for the
credential-scrubbed repair continuation. Resolving a thread after accepted
pushback removes it from the current finding set without requiring a no-op
commit. When the central profile requires review,
a clean Codex scan and a current human approval are both required, and a current
human change request remains authoritative. The same child merge-evidence gate
rejects every unresolved human review thread before parent integration. At most
seven later triggers are posted, so the initial scan plus retriggers cannot
exceed eight; remediation
after that ceiling records a durable `review_budget_exhausted` operator state
and uses the documented exact-commit local review path. Before
posting a later trigger, the scheduler persists the highest observed provider
comment ID so crash recovery can find the exact write despite GitHub's
second-precision timestamps. Recovery
keeps the cursor captured before the pending trigger instead of replacing it
with a later reconciliation snapshot. The
scheduler applies a fresh provider snapshot immediately before merge and returns
to review if approval, checks, or mergeability are no longer current. A merged
provider snapshot advances only when the pushed head and policy evidence remain
current and the durable ledger contains the orchestrator's pending merge intent
for that exact head. A replacement repair push supersedes older pending merge
intents; an external merge that bypasses those facts is blocked for operator
recovery. Repair
provider writes remain pending whenever a fresh tracker snapshot does not list
the parent in its active set, the controller is terminal, or the current
hierarchy generation is fenced. A
terminal or canceled tracker transition also persists controller cancellation
while the repair is between harness turns in pull-request, review, merge, or
refresh processing; no harness interrupt is emitted when no turn is running. A
repair implementation interrupted by restart remains in `fixing` for cleanup and
retry instead of entering the final-verification refresh path. A failed parent
verification selects the repository but does not publish immediately: the
scheduler creates the repair branch, resumes the same parent conversation for an
observed implementation-and-check turn, and only then commits and pushes through
the workspace owner. If that turn leaves no commit beyond the recorded target,
the scheduler clears its completion marker and queues another implementation
continuation. A repair request is accepted only when its receipt selects
a completed command observed by the harness before the attempt deadline. Repair
implementation retries stop at the configured scheduler limit, and provider
rate-limit responses defer all repair lookups until their retry delay expires.
While a parent is refreshing repositories, the scheduler requests complete
tracker details on the terminal refresh cadence so a failed verification can
retry without waiting for the hourly background scan.
After a provider merge, refresh fetches the configured target, proves the
recorded merge-result commit and every retained child merge result are
reachable, and refreshes complete instruction provenance before final
verification runs again. The configured repair merge
call selects merge, squash, or rebase centrally. Historical child merge evidence
can prove a merge commit from its multi-parent topology; GitHub does not expose
enough evidence to distinguish squash from rebase by a single-parent commit
alone, so an ambiguous result remains ineligible.
Child merge evidence accepts either Linear's suggested head branch or a stable
semantic branch beginning with the child's issue identifier, such as
`feat/COE-666-delivery`. Linear can change its suggested branch when the issue
title changes; an unrelated issue's branch remains ineligible.
Strict `opensymphony rehydrate` also derives the desired repository, harness,
model, and generation envelope from the current central routing inventory before
creating a replacement conversation. If that envelope differs from the
persisted run, rehydration stops and leaves the existing conversation intact
until the checkout is rematerialized or the configuration is reconciled.
When several configured aliases identify the same repository, recovery first
preserves and validates the alias recorded in the persisted binding; an alias
that now resolves to a different repository is rejected rather than silently
rewritten.
Terminal OpenHands archival uses the retry verification mode for the checkout.
That mode still requires the recorded generation, repository binding, ancestry,
and instruction provenance, while permitting ordinary worker commits or dirty
worktree changes that a terminal worker legitimately left behind.
When a route switches between OpenHands and Codex, the previous session remains
active until the replacement manifest has been durably written with the expected
runtime envelope and conversation binding; a failed replacement therefore does
not destroy the session needed for recovery. Before that replacement starts, its
previous conversation manifest is also recorded in
`.opensymphony/superseded-conversations.json`. Restart recovery and terminal
cleanup use that durable evidence to archive the old OpenHands conversation or
Codex thread, and successful retirement clears the evidence without overwriting
the replacement manifest.
Rollback refuses to proceed when the central catalog fingerprint differs from
the activation marker. This deliberate safety stop keeps captures made after
migration visible instead of restoring a legacy config that would hide them;
remove or reconcile the divergent catalog only through an explicit recovery
operation.
Central-config `opensymphony run` holds a destination-hashed
`.opensymphony/migration/strict-run-<destination>.active` marker until the
process exits. Rollback claims that same marker for its full restore, so it
cannot replace the active generation underneath a running instance, and stale
markers are reclaimed only after owner liveness is disproved. Graceful run
shutdown awaits the memory-server task before returning, ensuring its activity
marker and coordination lock are released.
Lock ownership treats permission-denied Unix PIDs as live, compares the
recorded process incarnation when available, and uses native process creation
times alongside `tasklist` for stale-lock recovery on Windows. Restart recovery
preserves successful
terminal workspaces according to the configured retention policy, rejects
pending retries that exceed a newly lowered retry limit, and redacts
credential-shaped diagnostics before persisting them in `run.json`. If a
terminal or nonterminal tracker transition cannot stop the remote harness,
the scheduler retains the execution and retries the interrupt on the next
reconciliation; terminal recovery also honors `workspace.retain_failed`.
Malformed central-only memory configuration is detected before legacy fallback
so it fails validation rather than polling or creating a workspace.
Activation markers are namespaced by the absolute central-config destination,
so separate instances cannot overwrite or consume one another's rollback
record.
Before enabling strict routing for any project set, follow
`docs/multi-repository-rollout.md`. The hermetic gate must pass at the clean
candidate commit and selected config hash. The first enabled set must be the
script-created disposable non-production set; its process, provider, tracker,
port, credential-copy, and workspace cleanup receipts are part of the release
evidence. Production project sets are enabled only by a later operator decision.
If an older target repo still contains `openhands.mcp`, remove that block.
OpenSymphony 1.0.0 expects Linear access through `LINEAR_API_KEY` and the
repo-local GraphQL helper assets copied by `opensymphony init`.
## ACP client validation and limits
`cargo test-system-duckdb --test acp` launches the reusable Python fake peer through
`opensymphony_acp::run_turn`, the same executable client API intended for host
integration. It requires Python 3, no provider credential, and creates a distinct
issue checkout inside a temporary workspace root. These subprocess tests establish
the client contract; real vendor qualification remains OSYM-906.
The default limits are 1 MiB per frame, 128 queued incoming frames with a
cumulative 4 MiB wire-byte budget, 128 outstanding callback responses with an
independent 4 MiB encoded-byte budget, 256 retained source frames with a cumulative
1 MiB serialized evidence budget, 16 KiB stderr, 30 seconds for setup, an
300-second prompt deadline by default for direct client callers, 10 seconds
for cancellation acknowledgement, and one 5-second
deadline for process termination and reaping. Windows launches enter a kill-on-close Job Object before
the child resumes, so dropping the turn future also terminates descendants. Unix
launches retain process-group ownership for the same drop path. Callers
may pass validated `ClientLimits`; a zero `prompt_timeout` disables only the
client's wall-clock prompt deadline. A supplied update channel must be drained
concurrently; saturation or receiver loss fails the run visibly. Incoming queue
charges are released when each frame reaches SDK dispatch. Its byte budget is
independent of frame count, ranges from 256 bytes to 64 MiB, and rejects a single
frame that exceeds it even when the per-frame limit is larger. Callback output
reserves count and encoded bytes (including LF) before SDK enqueue and releases
these only after stdin writes flush. Its count ranges from 1 to 4,096 and its byte
budget from 256 bytes to 64 MiB. Saturation fails promptly with ResourceLimit and
reaps the child, including when the peer stops reading stdin. Session creation
binds the new session ID in an ordered SDK response callback before subsequent
updates or permission requests are dispatched. Evidence capture
marks truncation when either the frame count or byte budget is exhausted. The byte
budget includes redacted payloads and source metadata, can be configured up to
16 MiB, and can be zero to disable retention. Frames that exceed the remaining
budget are omitted while protocol processing continues. Capture redacts secrets
and sensitive fields, including normalized account-identity keys; diagnostic
string previews are limited to 512 characters. Live update content preserves
whitespace and complete strings while removing known secrets and sensitive
fields; it does not use diagnostic preview normalization. Stderr overflow is replaced with a
limit marker while the pipe continues draining. SDK wire tracing is disabled for
this connection to prevent bypassing the redacted evidence surface. Known secrets
use one multi-pattern scan per string; matcher inputs are limited to 1,024 distinct
values and 1 MiB combined. Generic diagnostic normalization examines at most 2,048
characters after full known-secret redaction and emits a 512-character preview.
Non-authentication RPC errors retain the request method, numeric code, submission
state and bounded redacted message even when source-frame retention is disabled.
Cancellation before prompt submission interrupts setup and tears down the child;
an already-cancelled token prevents launch. The complete serialized prompt frame
must pass its size bound before submission becomes uncertain. Authentication
errors retain that submission state, so a mid-turn token failure cannot be
treated as a safe pre-submission login failure. Opaque session IDs remain
available for correlation and are omitted from diagnostic `Debug` output.
Only an original prompt response with `stopReason: cancelled` acknowledges a
requested cancellation. Sending `session/cancel`, killing a process, or receiving
an unrelated stop reason does not establish that acknowledgement. Prompt failures
after possible submission are uncertain and are never retried by this client.
ACP client facilities add independent defaults of 256 KiB per text file, 64 KiB
of retained output per terminal, 16 terminal handles/processes, 64 pending
callbacks, and a 300-second callback deadline. Pending callbacks also share a
`queued_bytes` byte budget independent of transport ingress. Callback response
reservations remain charged until stdin flush. An exceeded admission budget
fails the run visibly and tears down owned processes. Host policy disables all
filesystem and terminal callbacks by default. Output discards oldest characters
at UTF-8 boundaries; zero output retention is allowed. Scoped MCP headers,
environment values and credential option arguments join the redactor before any
wire frame is captured. Configuration RPC failures retain method, error code and
redacted context; authentication failures retain their dedicated classification.
Retained ACP ownership is available through `SessionHost`. A finished worker may
borrow the same live process again; nonpersistent agents remain attachable while
that process is alive. Owner loss allows only capability-gated restoration of a
known-finished session. `uncertain` prompt outcomes and launch-checkpoint gaps
require execution-risk reconciliation before another process can launch. Do not
clear a manifest marker merely because a local process exited: delegated remote
work can remain active.
An opted-in control server accepts a dedicated bearer token (at least 32
non-whitespace characters). `POST /api/v1/acp/{owner_id}` accepts generation-bound
`inspect`, `attach`, `renew`, and `release` actions. Observation leases grant no
prompt authority. `GET /api/v1/acp/{owner_id}/events?generation=N` returns private
SSE state/source events and explicit history-gap events when a bounded buffer or
subscriber loses data. Tokens belong in the Authorization header. Source frames
preserve redacted content and unknown payloads, with connection generation,
arrival sequence, run binding and replay origin. Recorded history is bounded by
the client's queue count and byte budgets. IDE writer handoff is a separate
integration slice.
### Production ACP routing
Configure `routing.harness: acp`, a named `routing.harness_profile`, and its
`acp.profiles` entry, then use `opensymphony run`. The gateway publishes profile
preflight readiness separately from negotiated run support. An unavailable
executable or missing credential reference is reported without exposing its value.
Retained profile identity survives a default-profile change on restart. A known
ACP profile and model are bound to the prepared run manifest. Recovery rejects
an older unbound prepared run when its workspace route snapshot belongs to a
different ACP run. Claims for a new run clear the old terminal result before launch,
so a crash at that checkpoint cannot complete the new run from the prior turn.
A known terminal prompt is reconciled without sending it again; a possibly submitted
prompt remains uncertain and blocks automatic retry and workspace removal.
Recovered finished turns reconcile only the matching run ID and attempt; a
prepared later run receives its own scoped memory environment and prompt.
An unfamiliar but nonempty bounded ACP `stopReason` is preserved as a finished
peer response and reported as an unsuccessful, non-retryable outcome. Known
credential values in the reason are redacted before durable storage and worker
status projection. The reason does not become an uncertain submission merely
because it is new.
The bound model includes a profile's `session.model` when no routing override is
set. Changes to managed memory run ID, attempt or project set rotate the retained
ACP process so child environment and memory evidence remain scoped to the run.
For an authoritative parent continuation, that rotation archives the old owner
but keeps the conversation manifest and session ID. The new process must
negotiate load or resume; an unavailable restore fails before another prompt
instead of creating a different parent session. A grant change that requires a
fresh conversation is rejected before parent retirement.
After a revoked memory grant requires a fresh owner, the revocation marker clears
when that owner reports a successful launch; failed setup leaves it in place.
ACP prompt guidance reads the managed worker overlay, not inherited shell scope.
The ACP child and its terminal callbacks receive memory variables only from the
run-scoped managed grant; ambient and workflow `OPENSYMPHONY_MEMORY_*` values are
discarded. Profiles cannot remap credentials into or out of that reserved namespace.
Repository-neutral ACP parents receive project, authorized-repository, run, and
attempt guidance from that overlay without an execution-repository default.
Production ACP turns have no fixed client prompt deadline. When configured,
`agent.stall_timeout_ms` applies the scheduler's activity-based stall policy;
the interrupt path handles an operator or scheduler stop request.
Unknown, redacted `session/update` variants produce bounded generic scheduler
activity. After a subscriber lag, the worker replays retained source frames when
they cover every frame after its processed cursor; an actual gap fences the run.
Supported filesystem callback requests and their responses produce payload-free
scheduler activity without recording file paths or contents.
Running terminal output polls and successful responses with a null exit status
likewise advance the idle deadline through payload-free activity; only an
observed exit code records command completion.
An ACP session restored through `session/load` receives the full workflow prompt
when its durable state has never seeded that prompt. A seeded session receives
continuation guidance even when the new run's claim has reset its status to
`ready`.
An exact-run `cancelled_before_prompt` checkpoint reports a cancelled worker
outcome on recovery.
Cleanup after a known-finished owner loss acquires the durable owner lock and
verifies the prior process is absent before recording its stop. Setup failures
before submission permit scheduler retry. Cancellation is accepted after
matching live or durable stopped-state observation. If the owner closes during
pre-submission cancellation, the scheduler verifies matching durable identity,
stopped process state and a `ready` or `finished` status before acknowledging.
Scheduled ACP interrupts identify the active worker by issue ID and issue
identifier, then verify its current owner, generation, run and conversation
before cancellation.
ACP permission and standard `elicitation/create` choice-form requests appear as
pending interactions for the selected run. Form capability advertises only the
form mode; URL elicitation is disabled. The supported form schema has one to
eight required string enum or string-array enum fields, with at most 32 offered
choices per field. Unsupported constraints, free-text fields, URL mode, and
secret prompts are rejected without exposing them in public snapshots. Web and
desktop Run Detail panels use offered permission option IDs and multiple-choice
form controls. Plan approval controls are typed for a registered extension;
The authenticated pinned Cursor `cursor/create_plan` request uses the plan
control when the profile enables its exact version registration. FrankenTUI shows a pending
request at the top of Issue Detail: `o` cycles requests, `,` and `.` page
through offered options, `1`–`4` selects a visible option, `[` and `]` cycle
questions, `s` submits complete answers, and `x` cancels. Question `n` declines.
The gateway exposes permissions and plans at `/api/v1/runs/{run_id}/approvals`, questions at
`/api/v1/runs/{run_id}/inputs`, and accepts bound responses through
`/api/v1/actions/dispatch`. A response must carry the live request, run,
issue, session, generation, and RPC binding token. The ACP responder retains the
original peer RPC ID privately; clients echo a generated public token. Stale,
duplicate, expired, and invalid option/answer submissions are rejected. A waiting interaction pauses
stall detection only until its deadline. Disconnect, cancellation, completion,
and restart clear the live responder; operators must wait for a fresh request.
Automatic `allow_once` and `deny` permission decisions require the same active
turn and are cancelled when a peer asks after its prompt has completed.
Callback arrivals and closures publish updated snapshots without waiting for
the next tracker poll. Timed-out callbacks retain their closure notification
through bounded channel backpressure, so pending requests clear when the worker
drains the queue.
An un-routed form request receives an ACP `cancel` response so a direct client
turn can continue. An operator-policy permission request without a route fails
the turn. A worker response that misses its acknowledgement deadline is fenced
before a failure receipt and remains pending for another answer attempt. An
answer already claimed by the ACP callback waits until the response frame is
flushed to the peer's input sink; a write failure returns a failed receipt.
The scheduler actor enqueues the response and applies the resulting receipt
when its worker-completion message arrives, so a slow peer does not hold up
tracker ticks, other issue updates, or shutdown. The terminal client waits for
the authoritative receipt without a total HTTP timeout; it bounds connection
establishment separately. Web and desktop invalidate an in-flight detail refresh
when a local operator answer is accepted, keeping answered controls removed.
The gateway also fences its queued command when its HTTP delivery deadline
expires or the handler closes. Once the run loop claims a command, the gateway
waits for the scheduler result instead of returning a premature timeout.
Only requests accepted into the scheduler's live pending set emit waiting
activity. Web and desktop retain selected form choices across live refreshes
while the same request remains pending.
Registered ACP harness operations appear in profile and active run capabilities.
An operator invokes `harness_operation` through the gateway with a run target
and advertised operation ID. The payload `run_id` is the current
`harness_capability.run_binding_id` in the run detail or snapshot. The service
binds the current run and session and
validates arguments before sending a structured result receipt. Permission
failure, stale binding, absent peer capability, invalid arguments, and disabled
registration reject the action. `fixture.echo` is read-only and available only
to `fixture_echo@1` profiles when the peer advertises
`opensymphony.dev/fixtureEcho: 1`; it exists for executable contract tests.
A deadline or disconnect after dispatch reports an unknown outcome, requiring
evidence inspection before any repeat. The event journal emits a correlated
completion or failure for each accepted dispatch. The pinned Cursor profile
supports observed plan approvals and ID-bearing todo requests; question, task,
image, and no-ID notification paths remain unqualified. The captured wire
contract and production test are in
[acp-extension-evidence.md](acp-extension-evidence.md).
Todo activity follows the correlated accepted callback result. Duplicate
in-flight peer IDs across plan, todo, and standard callbacks remain ambiguous
until all matching responses drain. More than 16 unresolved todo requests or
128 concurrent callback IDs emits a diagnostic and fences the worker.
The outbound operation's response can complete after the prompt finishes;
prompt completion does not cancel its separately bounded RPC wait. A deadline
returns outcome unknown to the caller while keeping that unresolved SDK request
inside the eight-operation limit until its reply or connection closure. Peer
results are redacted with the session's known secrets before entering the public
action receipt, including strings in `value` and `_meta`.
## ACP live qualification and recovery
Run the ignored authenticated tests in [ACP live
qualification](acp-live-qualification.md) after checking both pinned CLI
versions and local login status. The report separates the local profile
preflight result from a completed tracked issue run. Cursor and Devin both
advertised `session/load` and restored a known-finished session; neither
advertised `session/resume` in this qualification. An unadvertised optional
method must not be assumed. A credential or option failure before prompt
submission is a setup failure; a possibly submitted prompt is fenced from
automatic resend and cleanup until reconciled.
## 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-275: Remote agent-server mode and auth hardening
- 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-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-389: Current Gateway Inventory And Vocabulary
- COE-390: Gateway Schemas And Stream Feasibility
- COE-391: Gateway Module, Capabilities, And Dashboard Snapshot
- COE-392: Task Graph, Run Detail, File, And Diff Read APIs
- COE-393: Event Journal And Stream Broker
- COE-394: Frontend Workspace And Shared Schemas
- COE-395: Planning Artifact Schema And Session Service
- COE-396: Action Receipts And Initial Run Actions
- 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-448: Multi-repo memory server and deterministic context
- 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-494: Project Metadata For Operator Issue Snapshots
- COE-495: FrankenTUI Project Headers And Dependency Gutter
- COE-496: Desktop Project Grouping And Collapse
- COE-497: Project Grouping 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-275
- COE-277
- COE-278
- COE-280
- COE-281
- COE-282
- COE-284
- COE-286
- COE-287
- COE-293
- COE-294
- COE-382
- COE-383
- COE-384
- COE-385
- COE-386
- COE-387
- COE-389
- COE-390
- COE-391
- COE-392
- COE-393
- COE-394
- COE-395
- COE-396
- 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-448
- 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-494
- COE-495
- COE-496
- COE-497
- 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