Code map · Architecture · Test map
Discovery, model import, saved model routes, task collaboration and Worker execution are separate capabilities. They share configuration and lifecycle owners; native leaves supply only the ecosystem differences. A successful local check establishes a prerequisite, not a model call, installed Skill invocation or resumable task.
Qoder/Pi/DSH/OpenCode saved models use one owned provider per Plan with an explicit
Responses/Messages choice. Route grants
and Gateway trust preserve alias,
protocol and receipt authority across publication/restart. work.protocol is the
independent frozen Worker choice. Publication budget guards
report the actual installed consumers; safe conflict facts
retain rejection identity through compensation and client observation.
The published Codex parallel-tool opt-out is enforced before native/IR request
projection in Gateway authority;
listener cases
cover native and cross-protocol forwarding.
Native defaults and collaboration stay independent;
restoration must verify ownership rather than infer it from a provider name.
The Linux standalone Agent removal gate
coordinates settings Apply, Restore, retry and startup recovery with the
installer's exclusive teardown.
Native routing resources
use the same protected artifact journal as model settings. The
request-purpose boundary admits
main/child history and detaches known auxiliary calls; listener regressions
cover interleaving and semantic compaction independently of provider affinity.
Pi's provider adapter binds native
compaction/tree-summary signals at the public provider seam and retains branch
cursors as observed evidence. Its native guide
separates installed SDK fixtures, actual CLI acceptance and Restore inference.
Claude's native identity leaf
keeps session/agent scope separate from its request-class and prompt leaf;
known auxiliary classes survive optional enrichment failure, while unknown classes
retain complete observed input and normal routing.
The native continuity owner
separates known continuations from usable observed input. Missing origin proof
retains classification, actual capture and evaluation in an uncertain lane without
replacing verified task history. Native identities remain scoped independently;
Qoder's shared main/child identity has an accepted association limit. Follow the
routing contract
for recovery limits rather than equating successful output with full adaptation.
The v2 input consumer keeps an omitted optional input descriptor distinct from an invalid declaration. Input projection reports the former as correlation only without selecting a human window. DSH's late model-selection notification is covered by the producer controls and projection controls; the unchanged wire request remains available to normal routing and capture. The DSH producer recognizes native runtime, skill-catalog, time-context and repeat-tool-reminder supplements, and validates both retained instruction roles and older User-role projections against the complete final User scope. Unknown producers still lose the optional input proof. Native failed-request retry association belongs to the shared history owner, not to the DSH adapter or a session-wide lock.
Codex's native metadata parser validates coherent protocol identities and windows independently of User-Agent versions. Its Responses input adapter recognizes empty output probability metadata already accepted by the response parser; unknown/nonempty enrichment stays opaque. ACP listener regressions cover replayed commentary, tool continuation and complete next-stage assessment.
Codex's connection guidance
explains native provider-scoped session discovery before enabling routing. Default
on-demand access preserves the ordinary entry for earlier sessions; advanced default
takeover first requires configuration restoration. See session recovery. Worker Continue below
has its own exact-history binding and does not replace the native /resume picker.
The separate Codex Desktop instance
uses a distinct home and settings identity alongside that CLI slot. Its
native command binds launch
to fresh configured status through the model-only native Session reader,
retaining the originating window, Session and service fences without loading Plans
or Skill inventories; host preparation
shares user skills without replacing existing entries;
the Windows Shell entry and
local CLI action share the
exact-context launch reader and
native effect. Web consoles
copy that context-only local command without reading the Plan catalog; package
discovery, fresh authority checks and graphical launch stay on its host.
The Windows package lookup
passes the registered MSIX image identity to both entries. The
package image reader opens the
known file without enumerating WindowsApps and checks its identity on reuse.
The scanner reports an unsuccessful AppX query or image inspection as unavailable.
Windows skill junctions and Unix symlinks share the exclusive
directory-link boundary.
Its model identity remains separate. The settings planner
uses the private configuration and existing ownership records to restore even if the
Desktop application has been removed. Management uses the original CLI/root owner
and shared user file through the UI owner resolver
and shared status projection.
DSH Desktop likewise uses its DSH_HOME Web owner's management Skill. Neither adds
a Worker executor or collaboration control. Desktop-only management admission
and wire/reopen/restore coverage
preserve canonical references when no separate CLI is installed.
Lifecycle coverage
exercises both connections and recovery through the public settings wire.
The trial flow preserves that selected mode. After confirmed mapping, its handoff reads only the submitted native context, verifies its saved selection and reuses the shared profile command/copy view. Default mode instead explains restarting the matching CLI/Desktop. The independent Desktop instead links back to its exact Agent connection for the separate-window or local-command action. Explicit result refresh retires the earlier launch instructions; unverified, changed or revoked settings cannot supply confirmed guidance. OpenCode's startup target binding keeps the physical JSON/JSONC file verified by existing recovery markers; effective model facts also feed the shared configured/drift status. Its ordinary routing producer freezes per-call purpose/session before a bounded optional SDK page; exact native page positions provide compression references while synthetic continuations keep unavailable-input semantics. The OpenCode guide separates hook regressions from native dependency initialization, recovery and Restore inference; a hook deadline cannot bound the native loader that precedes it. The persisted OpenCode metadata fallback is decided by additional-model facts before writes and uses the existing model Restore/Apply journal. Its settings regressions cover restart, re-enablement, borrowed resources and stale previews; it changes metadata precision without changing model authorization or Gateway routing. Its bounded Markdown reference reader adds native user Agent/Mode selectors to the same settings dependency checks; removal requires complete references, while retaining selectors permits grant rotation. Worker project ancestry uses the native Git boundary check with the filtered child HOME/XDG/PATH and shared bounded probe process. Both configuration and resource inspection require a confirmed Git stop or the filesystem root within the existing bound; an invalid marker or unavailable Git cannot truncate admission. The shared probe process owner retains an exited Unix leader until group signals finish. Only a still-running leader receives termination grace; completed probes immediately stop surviving group members and still require reap and proven group absence.
Hermes uses an explicit effective profile and one default main-model Plan. Desktop keeps Hermes in the common Agent list; its native host resolves the caller's existing default profile and its details can select another through the same target-read flow before settings become available. The common discovery preference remembers explicit targets as hints, with backend revalidation and per-profile failure isolation. Startup protected-input priming reads exact native configuration descriptors without running informational version probes; explicit Agent inventory retains full discovery and later secret reads recheck source revisions. Its native request middleware carries the real session into trusted Gateway correlation and emits observed batch context independently from optional bounded read-only compression evidence; clean callback text and retained legacy hints cannot select an input instance. Gateway routing evidence validates compression scope independently of task-envelope parsing, so an adapter fault and recovery cannot strand otherwise comparable captured history. The managed provider also uses the same scoped model grant as its native API key for auxiliary Chat requests; global model headers are not a credential carrier. All six supported Agents have independent management and collaboration Skills; shared Skill facts resolve their native roots through the existing ownership/Operation engine. Legacy primary roles retain their original resource meanings; the second Skill has a separate registered effect and per-facet restore reference. Hermes initiates delegation through the existing local Worker CLI and does not become a Worker executor.
| Step / question | Production owner | Boundary to preserve |
|---|---|---|
| Select and confirm an installation | Metadata discovery, protected confirmation, launch type, storage | Canonical selectable components and explicit platform variants, window-bound single-use confirmation and durable selection; discovery is not authority |
| Publish the machine-readable request shape | Worker producer, Plan producer, CLI generator | Typed producer sources generate CLI contracts; retain native-only forbidden fields and adapter requirements |
| Submit and admit work | CLI submission, daemon admission, Application | Daemon admission owns durable key/intent deduplication; CLI preserves returned locators and uses no local receipt |
| Wait for completion or the next progress revision | CLI observation loop, bounded daemon observation, saved result read | Completion and optional result retrieval share a deadline when supplied. Explicit revision watching retains one observation. Stopping the observer leaves work active. CLI boundary scenarios |
| Resolve resources and construct a run | Installation, native context, profile guide | Effective instance HOME/config root supplies resources; per-run overrides supply route, credential and permission policy |
| Project native context/output budgets | Shared budget policy, native projection | Preserve the frozen Plan's active-candidate/protocol bounds; Gateway output capping alone cannot prove native compaction limits |
| Admit and attribute model requests | Run authority, Gateway dispatch | Sealed Plan, live run, harness, protocol and observation identity must agree |
| Confirm the native session/model | ACP model confirmation, ACP driver | Confirm typed mode before the final typed model for OpenCode; confirm the exact native model before prompt; missing capability cannot silently change the route |
| Continue the same task | History binding, resume | Restore the exact frozen context/session with a fresh credential; never select the newest history or start a replacement conversation |
| Start, cancel and finalize processes | Executor, OS launcher, finalization | Explicit argv/environment/materials and owned process identity; stopping and successful task completion are separate facts |
| Explain execution failures and Qoder account selection | Host progress, run request diagnostics, account guide | Durable stage/reason facts are shared by CLI status, waits, cancellation and submission replay; fixed explanations and the rendered Qoder directory use ordinary progress; cleanup cannot invent user cancellation or change a task's native context |
| Read, hide, expire or clean up content | Reads, Continue admission, maintenance, native cleanup | Saved progress is independent of execution/cleanup state; current content permission and exact cleanup ownership still apply; borrowed history is not a deletion target |
The public Worker CLI submits autonomous runs with approve-all. Its input owner
rejects explicit permission options before submission; the native profile owner
still enforces policies carried by existing Local Control or persisted runs.
Claude's session-mode admission and root/native-policy guidance belong to the
ACP driver and
profile guide; discovery
of executable dependencies does not establish autonomous-mode availability.
| Ecosystem | Resource context | Worker transport / native owner | History and acceptance |
|---|---|---|---|
| Codex | HOME/CODEX_HOME and project Skills | Selected ACP adapter; profile | Borrowed native history, exact session; native context guide |
| Claude Code | HOME/CLAUDE_CONFIG_DIR and project Skills | Selected ACP adapter with protected environment; profile | Borrowed transcript, exact identity and flush; native context guide |
| Qoder | HOME/QODER_CONFIG_DIR and project Skills | Selected native ACP CLI; profile | Borrowed opaque history, exact ACP load; Qoder guide |
| Pi | HOME/PI_CODING_AGENT_DIR, project and installed package Skills | Selected npm CLI + Node, bundled SDK→ACP bridge; profile | Task-owned v3 transcript, validated before open; Pi guide |
| DeepSeek Harness (DSH) | HOME/DSH_HOME, project and custom Skill roots | Selected native ACP CLI and public run patch; profile | Task-owned opaque history, exact ACP resume; DSH guide |
| OpenCode | HOME/XDG, explicit config and additive resource roots, project Skills | Selected native ACP binary; profile | Borrowed opaque SQLite history, bounded format admission and exact ACP load; OpenCode guide |
OpenCode's passive Agent and Worker discovery also inspect the official installer's
~/.opencode/bin directory when a GUI launch lacks its shell PATH. Agent discovery
keeps the PATH entry first; a saved explicit installation never falls back to a
different binary. This does not grant a Worker selection or native-format capability.
The profile guide owns startup flags, credential delivery, native tool permissions and resource restrictions. Do not duplicate the shared admission, process or retention lifecycle for an ecosystem.
On Windows, native launch admission
resolves the declared entry of known npm producers. Native PE entries run directly;
JavaScript entries use the selected Node. Both launch paths share this dispatch,
and native authentication evidence binds the actual PE identity even while its npm
shim stays unchanged. The native npm regression
executes the declared image without Node and rejects a changed engine identity.
The .cmd shim is never evaluated. Shared executable discovery
continues a Windows PATH search after an unusable entry, retaining the failure if
no candidate passes path admission. Explicit selections report that failure at
the selected path. DSH PATH discovery
continues after unusable candidates and can follow a standalone shim to its
declared DSH npm entry, including the generated npm form with a relative target.
The public composition check binds the chosen native program and its declared
entry alongside the launcher. Qoder lookup
can confirm a missing candidate behind a PATH junction while retaining strict
admission for an existing executable. The Windows public scan regression
runs the Claude PATH walk, both DSH lookup paths and the two Desktop-only Codex
entries through a production Control daemon with temporary roots. System shell
selectors come from the actual Windows system directory. Worker and CPA subscription-source HOME discovery use
the same account native-profile selector in the daemon control runtime,
while explicit ecosystem configuration roots retain their existing meaning.
Managed Claude drive paths
project Rust's verbatim spelling only after reparse-free native file identity
checks. Discovery and launch share that boundary; the launch retains the selected
image and trusted helper handles. UNC and device aliases remain outside this contract.
Live checks
capture output in private files and retain the process Job until all owned tools
stop. Follow those owners for shell, environment, timeout or background-session
differences rather than duplicating ecosystem lifecycle code.
OpenCode's isolated collaboration probe pins the system Windows PowerShell and
quotes the public CLI for that shell. The native tool ID bash does not imply
Git Bash. Its npm locator uses the shared declared-producer reader after PATH
resolution, then selects the unique native platform package without running a shim.
The Windows Qoder collaboration probe
retains the actual Skill directory and file before launching the client. Its
receipt binding
accepts equivalent disk spellings only after native identity, captured permissions and
content checks; it rejects foreign/reparse paths, changed files and split messages.
The HTTP peer still requires
correlated native Skill and CLI results. No credential contents enter these checks.
The shared private-directory projection
binds Qoder and Claude's Git Bash working/temporary roots to an ordinary drive
spelling of the same retained private directory. Qoder's
workspace receipt
also verifies its fixed cwd notice against that retained identity.
Qoder's Bash call uses Git Bash syntax on Windows: the selected CLI's native DOS
path is quoted for Bash. The separate PowerShell tool is not that execution boundary;
see the probe ownership guide.
The Codex collaboration check selects the native restricted-token sandbox for its Windows read-only process. Its independent write rejection control must observe the actual shell's denied write before accepting Skill reads and execution of the public CLI; a policy rejection before shell execution is not successful sandbox evidence. Its closed tool-output facts are observed before failed receipt checks return, so early rejection retains fixed execution-header facts without logging native output or session identifiers. Nonce-bound script checkpoints retain the entered phase, fixed language mode and numeric failures; they cannot replace the actual denied-write receipt. Follow the read-only control owner for the Windows parse-only gate and shell boundaries.
CLI dependency input projects ordinary local drive paths to the existing canonical selection before transport, retaining file and ancestor leases through the call. Already canonical requests preserve completed-operation replay even after the selected files disappear; Application still owns the canonical tuple, revision and durable transaction. The shared npm reader lets callers inspect original manifest and declared-entry names before reading or canonicalizing them. The Pi locator uses that boundary to bind a generated shim to the package's declared entry and manifest digest without evaluating the shim or changing borrowed ownership. Direct Pi entries retain the single package reader and its nearest-match semantics; original declared-bin names are inspected before canonicalization, so an alias cannot disappear from the identity check.
Selected dependency checks allow bounded cold startup: native version reads have a 10-second deadline and the offline Pi SDK check has 15 seconds. This is separate from directory discovery's scan budget and from the admitted task deadline. A timeout does not invalidate the saved selection or consume a submission key. Failures expose a closed check stage and reason through the existing machine error message key, with transient inspection/timeouts marked retryable. No native output, environment value or credential is included. A dependency failure after admission leaves the run Failed and writes an explicitly HiRoute-authored reason to its existing progress stream, never a successful model result. The same selection and exact Continue request can be retried after a transient check.
The existing error envelope and managed progress format remain current; this adds no saved dependency fields, schema conversion or alternate legacy reader.
Runtime admission and the SDK contract bind the selected CLI's declared executable and SDK export from the same package. Production checks interfaces required by the operation, not the acceptance release label:
- Static import and saved-model configuration do not require Worker session APIs.
- Collaboration requires the native resource loader and read/bash/public CLI path.
- New work requires provider/key binding, resources and new-session interfaces.
- Continue additionally requires native open and the exact supported transcript; missing history never falls back to creating a new session.
The bridge keeps an empty in-memory credential store, offline package discovery and task-owned history. It validates branch-local v3 context edits without rewriting original messages. Process regressions cover creation/cancel/disconnect races; failure ingestion maps closed failure stages without exposing native exception text. These checks do not replace real native compaction, Continue or concurrent-route journeys.
Official Desktop admission
checks the bundled provider API for independent profiles/desktop settings.
The owned routing entry registers
HiRoute's provider routes alongside user plugins. Admission and the Host resolve
the same provider exports from the running Electron app's bundled resources.
Native restore
recognizes both released provider placement and the independent Desktop entry.
The shared native restore boundary
checks the bytes used to render a confirmed Disable against its accepted snapshot.
Windows rescans check Programs directories and read-only uninstall hints
through native registration inspection.
The scan response
retains Web lookup and launch failures and supplies context-scoped remediation actions.
The Web entry retains profiles/web ownership; both reuse protected additional
provider effects and bundled routing registration. Desktop discovery does not
require npm DSH, and its model support does not advertise Worker/Skill support.
DSH uses public CLI/configuration and native ACP; there is no SDK import or native history decoder. Static source/configuration rules belong to the native leaf. Local capability checks inspect public composition without model activation and keep collaboration resources independent of model-provider edits. Settings discovery reads native files without a version subprocess. The facts capture owns one public composition probe per capture and checks its dependencies after both native snapshots; Preview, Apply and locked admission keep independent proofs. Agent settings responses carry the Desktop admission reason in the error envelope for CLI and Desktop.
The Worker profile
adds a final run-owned patch while preserving borrowed resource roots. Continue
requires advertised session/resume, the exact native/ACP session ID and frozen
context/route; DSH interprets its own history. Missing or unusable history fails
without session/new. Custom compositions and cross-version continuation require
separate evidence; an acceptance pin is not a production version allowlist.
Codex adapters missing AIR sessionFailure fail during actual initialize, before
session creation/load. The ACP owner
adds an actionable [HiRoute] reason to the existing Worker progress window;
lifecycle flushes it after owned
process cleanup. This host explanation is separate from the model result.
Claude terminal finalization keeps ACP live while the exact native transcript drains after result publication and credential revocation. Terminal tool/text admission closes first; bounded history observation controls Continue eligibility. An interrupted observation retains the published result and finalization lease with history readiness false. Follow the ACP guide and causal tests for this ordering; installed native tools and Continue require their own acceptance.
The task root owns context descriptors and exact-session bindings. Run roots own temporary launch materials and credentials. Borrowed HOME/config/history remain native-owned; Continue reads the original descriptor rather than today's service environment. Pi and DSH history is task-owned, but permission to Continue still comes from HiRoute's current task/content state.
Only registered old Codex/Claude tasks may use the legacy private-root recovery
path in the compatibility registry.
A corrupted current binding is not legacy absence. Resource discovery and native
permission policy are separate; using one OS account does not make HOME a sandbox.
The legacy scanner encodes filesystem components with / at the retained-path
boundary; native Windows separators do not change that portable contract.
Preparing is committed before any native process can spawn. Cancelling an
Accepted run therefore atomically records Cancelled with complete cleanup;
a stale executor cannot cross the preparation revision check. Once preparation
has started, cancellation still needs owned-process stop evidence. Startup may
settle the old revision-2 Cancelling record only when the exact record proves
that preparation, process binding and prompt intent never occurred.
An ended Unknown outcome can have complete cleanup. Its cancel is idempotent;
stored checkpoints
reject later observations that would revoke the same run's complete scope-stop
proof. Role shutdown signals the
executor and joins Worker
finalization under its existing deadline before process/store teardown.
Interrupted lifecycle runs
stop their scopes concurrently before taking the finalization lease to record
stop evidence. The persistent journal
revokes the attempt credential as soon as it persists an execution failure.
The shared startup coordinator protects same-daemon Codex borrowed-root initialization and OpenCode database initialization. OpenCode rechecks the captured configuration and read-only database admission after waiting on its frozen database path. Coordination ends at successful ACP initialize, before session creation/load or prompt; tasks remain concurrent. An unconfirmed initializer retains occupancy until owned stop verifies its exact process. Retry Cancel through the existing task action; residual acknowledgement or daemon restart is not proof that the original processes stopped. Other roots and clients retain independent execution.
| Behavior | Start with |
|---|---|
| Installation confirmation, one-shot authority and exact saved selection | Shared session tests, Desktop scenario map |
| Actual user/project Skills and exact Continue after restart or source replacement | Native context journey, ecosystem acceptance guide above |
| Concurrent routes, cancellation isolation and missing-history rejection | Shared boundary journey, assertion guide |
| Native tool summarization and compaction remain on the frozen route | Compaction journey, Qoder native leaf |
| Token-free startup, foreign settings preserved, exact history and cleanup | Profile tests, history tests, material tests |
| Unconfirmed initializer recovery, credential revocation and owned stop | Startup journeys, journal tests, platform tests |
| Hidden/expired content blocks read and Continue; borrowed neighbors survive | Read/Continue journey, maintenance tests |
Use the test map and selected ecosystem run guide for inputs, writable
roots, required outcomes and cleanup. Shared request changes require the configured
Mac desktop-pilot --all-targets compile gate; ignored native targets need explicit
execution. Shared Product Session filters are commands::worker_tasks::tests,
session::checks::tests and commands::model_connection_web::tests; zero selected
tests prove nothing about those consumers.
The OpenCode native Windows leaf is
windows_opencode_business.rs,
selected by actual_windows_opencode_worker_native_history_and_cancellation in
windows_headless.rs. It shares the
public routing/Worker receipt oracle and Job cancellation assertions with existing
Windows acceptance; it adds no alternative production lifecycle.
Model-only post-save confirmation reuses the exact model projection in
trial_agents.rs;
its authority fences remain independent of retained discovery hints. Unread Skills
are read when their editor opens. Codex/Hermes target-sensitive reads and explicit
selected discovery are owned by
agent_discovery.rs
and the shared
Agent snapshot reader.
The exact context crosses ScanAgents; full discovery remains explicit. Agent
settings effects are prepared once under the Application writer in
prepared.rs.