Explain deployment compose-service lookup failures

Context

The deployment-state bridge is supposed to provide bounded, read-only service diagnostics to public KB/MC tools without exposing Docker socket, shell, or lifecycle authority. During cloud diagnostics, the snapshot was fresh and readable, but every allowed compose service entry degraded with No Docker container found for compose service '<service>'.

That error is too thin for operators and agents to resolve safely. It does not say which compose project filter was used, which service keys were allowlisted, whether the Docker socket was reachable, whether the stack uses different Compose service labels, or whether the bridge is simply not configured to observe the orchestrator service that owns scheduler tasks.

Live latest-open sweep: checked the latest 20 open issues at 2026-07-01T15:03:36Z; no equivalent found. Targeted searches for compose service No Docker container found deployment diagnostics, deployment-state bridge tenant repo sync, and tenant-repo-sync diagnostics found no equivalent issue. A2A in-flight sweep: checked recent 30 messages; no active overlapping [lane-claim] / [lane-intent] found.

The Problem

inspect_deployment can return a fresh snapshot that appears structurally healthy while the service-observation layer is not actually observing the deployment. When service resolution fails for all expected services, operators need a configuration diagnosis, not four independent service-level errors.

Current failure mode:

• DeploymentRuntimeAccessService.resolveServiceTarget() filters Docker containers by com.docker.compose.service=<serviceKey> and optionally com.docker.compose.project=<composeProject>.
• If no container matches, the public snapshot only reports No Docker container found for compose service '<serviceKey>'.
• The snapshot does not expose the effective composeProject, allowed-service list, filter shape, or bridge-level conclusion that all service lookups failed.
• The default observed service set does not include the orchestrator service, even though orchestrator-owned scheduler/task diagnosis often depends on orchestrator logs and task state.

This blocks root-cause analysis for cloud incidents. A deployment can have healthy MCP servers and Chroma connectivity, while the deployment bridge cannot prove whether the sibling containers and orchestrator task runner are alive or correctly configured.

The Architectural Reality

Relevant existing substrate:

• ai/daemons/orchestrator/services/DeploymentRuntimeAccessService.mjs owns Docker-socket read/lifecycle envelopes and resolves service keys through Compose labels.
• ai/daemons/orchestrator/services/DeploymentStateBridgeService.mjs writes the bounded snapshot consumed by inspect_deployment and get_deployment_state_snapshot.
• ai/config.template.mjs defines runtime access keys, including NEO_ORCHESTRATOR_RUNTIME_ACCESS_COMPOSE_PROJECT, NEO_ORCHESTRATOR_RUNTIME_ACCESS_ALLOWED_SERVICES, and NEO_DEPLOYMENT_STATE_BRIDGE_ALLOWED_SERVICES.
• inspect_deployment is the public diagnostic facade; it must be actionable when the bridge itself is misconfigured.

The Fix

Improve the deployment runtime bridge diagnostics so compose-service lookup failures explain the bridge configuration and likely next checks without exposing secrets or arbitrary Docker state.

Concrete direction:

• Add bridge-level summary when all or most allowed services fail lookup.
• Include bounded effective config fields: runtime mechanism, whether runtime access is enabled, composeProject value or null, allowed service keys, read operations, bridge allowed service keys, and whether logs are included.
• Include the Compose label filter shape used for a failed lookup, without arbitrary Docker container enumeration.
• Distinguish Docker socket unavailable / disabled / forbidden operation / no matching container / multiple matching containers.
• Evaluate adding the orchestrator service to the default diagnostic allowlist, or document the required env override to include it in cloud deployments.
• Add operator hints for common fixes: set the compose project, align service names with Compose labels, mount Docker socket when B1 runtime access is intended, or disable runtime access explicitly when unavailable.

Contract Ledger Matrix

Decision Record impact

No ADR amendment expected. This stays inside the existing deployment-state bridge and runtime-access contracts; it improves the observability of the cloud deployment diagnostics.

Acceptance Criteria

• Compose lookup failures include stable structured reason codes.
• inspect_deployment includes bridge-level aggregate diagnosis when service resolution broadly fails.
• The diagnostic exposes effective non-secret runtime-access and bridge service configuration needed to resolve label/project mismatches.
• The surface distinguishes socket/disabled/allowlist/no-match/multi-match failures.
• The orchestrator-service observability decision is implemented or documented with an explicit cloud env override.
• Tests cover the major failure classes and assert that secrets/raw env are not exposed.
• Cloud troubleshooting docs describe how to interpret and fix No Docker container found for compose service ....

Out of Scope

• Exposing arbitrary Docker APIs to public MCP clients.
• Adding lifecycle write authority to KB/MC diagnostics.
• Changing container names or Compose project naming policy.
• Solving tenant-repo-sync task-state observability; that is tracked separately in #14396.

Related

• #14396
• ai/daemons/orchestrator/services/DeploymentRuntimeAccessService.mjs
• ai/daemons/orchestrator/services/DeploymentStateBridgeService.mjs
• ai/config.template.mjs
• learn/agentos/cloud-deployment/Troubleshooting.md

Origin Session ID: c0dfa949-22de-4daf-bbd2-1e093383fefc

Handoff Retrieval Hints: deployment runtime access compose service lookup, No Docker container found inspect_deployment, deployment-state bridge service resolution